# Azione!Lab

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.