generated from bisco/codex-bootstrap
bisco
139 lines
4.7 KiB
Markdown
139 lines
4.7 KiB
Markdown
# Laboratorio Teatrale
|
|
|
|
A warm, editorial single-page website for a contemporary theatre workshop. Wagtail
|
|
provides an editor-friendly headless CMS, Astro renders the public site, PostgreSQL
|
|
stores content, and Docker Compose supplies a reproducible local environment.
|
|
|
|
## Architecture
|
|
|
|
- `backend/`: Django and Wagtail admin, content models, media uploads, and the
|
|
aggregate read-only API at `GET /api/site/home/`.
|
|
- `frontend/`: Astro components, responsive design system, typed API adapter, and
|
|
Italian fallback content for development when the CMS is unavailable.
|
|
- `postgres`: persistent CMS database.
|
|
- Docker volumes: `postgres_data` for the database and `media_data` for uploads.
|
|
|
|
See [the architecture document](docs/architecture.md) and
|
|
[ADR-0001](docs/adr/0001-headless-wagtail-astro.md) for the rationale.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker Engine with Docker Compose v2.
|
|
- Ports `4321` and `8000` available on localhost.
|
|
|
|
No host Python or Node.js installation is required.
|
|
|
|
## Start locally
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
docker compose up --build -d
|
|
docker compose ps
|
|
docker compose exec backend python manage.py seed_demo
|
|
```
|
|
|
|
Open:
|
|
|
|
- public site: <http://localhost:4321>
|
|
- Wagtail admin: <http://localhost:8000/admin/>
|
|
- aggregate API: <http://localhost:8000/api/site/home/>
|
|
|
|
The frontend remains usable with curated fallback content if the API is unavailable.
|
|
On first startup the backend applies migrations and collects static files before
|
|
starting Gunicorn. Wait until `postgres`, `backend`, and `frontend` report healthy.
|
|
|
|
## Create an editor account
|
|
|
|
```bash
|
|
docker compose exec backend python manage.py createsuperuser
|
|
```
|
|
|
|
Sign in to Wagtail at <http://localhost:8000/admin/>. The public site has no user
|
|
accounts or authentication.
|
|
|
|
## Demo content
|
|
|
|
The seed command is idempotent and creates or updates the initial home page, site
|
|
settings, participation cards, teacher, lessons, shows, gallery entries, and local
|
|
placeholder images:
|
|
|
|
```bash
|
|
docker compose exec backend python manage.py seed_demo
|
|
```
|
|
|
|
Re-run it only when you intentionally want to restore the demo records. Content edited
|
|
after seeding may be overwritten for records managed by the command.
|
|
|
|
## Editing content
|
|
|
|
1. Open Wagtail admin and select **Pages** to edit the home hero, introduction,
|
|
laboratory section, and the three participation cards.
|
|
2. Select **Settings > Site settings** for the workshop name and contact details.
|
|
3. Use **Snippets** for the teacher, lessons, shows, and gallery.
|
|
4. Publish page changes. Snippet and settings changes are returned immediately by the
|
|
aggregate endpoint.
|
|
|
|
The frontend reads `PUBLIC_CMS_API_URL`; inside Compose it defaults to
|
|
`http://backend:8000`. Media URLs use `WAGTAILADMIN_BASE_URL` so browsers receive the
|
|
public `http://localhost:8000` address. Change both values for another environment.
|
|
The standard published-page endpoint is also available at `/api/v2/pages/`.
|
|
|
|
## Useful commands
|
|
|
|
```bash
|
|
# Follow application logs
|
|
docker compose logs -f postgres backend frontend
|
|
|
|
# Run database migrations
|
|
docker compose exec backend python manage.py migrate
|
|
|
|
# Run all required checks in containers
|
|
docker compose run --rm backend python manage.py test
|
|
docker compose run --rm frontend npm run check
|
|
docker compose run --rm frontend npm run build
|
|
docker compose config --quiet
|
|
|
|
# Stop the stack without deleting content
|
|
docker compose down
|
|
|
|
# Stop and permanently delete local database and uploaded media
|
|
docker compose down --volumes
|
|
```
|
|
|
|
The final command is destructive. It is useful only when intentionally resetting the
|
|
local environment; run the seed command again after the next startup.
|
|
|
|
## Directory structure
|
|
|
|
```text
|
|
.
|
|
├── backend/ # Wagtail/Django CMS and API
|
|
├── frontend/ # Astro public website
|
|
├── docs/ # Architecture, operations, security, and ADRs
|
|
├── docker-compose.yml
|
|
├── .env.example
|
|
└── README.md
|
|
```
|
|
|
|
## Database and media backups
|
|
|
|
Database rows and uploaded files must be backed up together:
|
|
|
|
```bash
|
|
mkdir -p backups/media
|
|
docker compose stop frontend backend
|
|
docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > backups/database.sql
|
|
docker compose cp backend:/app/media/. backups/media/
|
|
docker compose start backend frontend
|
|
```
|
|
|
|
This brief maintenance window keeps database rows and uploaded files in sync. See
|
|
[operations](docs/operations.md) for the destructive restore procedure and its
|
|
cautions. Do not commit database dumps, `.env`, or uploaded media.
|
|
|
|
## Production TODOs
|
|
|
|
This repository deliberately targets a simple, working local deployment. Before a
|
|
public production launch, add a TLS reverse proxy, production-grade static/media
|
|
serving, off-host backups, monitoring, and a deployment-specific secret manager.
|