generated from bisco/codex-bootstrap
bisco
154 lines
5.2 KiB
Markdown
154 lines
5.2 KiB
Markdown
# 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.
|
|
- `nginx/`: reverse-proxy virtual host for `azionelab.org`, routing public requests to
|
|
Astro or Wagtail.
|
|
- `postgres`: persistent CMS database.
|
|
- Docker volumes: `postgres_data` for the database and `media_data` for uploads.
|
|
|
|
See [the architecture document](docs/architecture.md),
|
|
[ADR-0001](docs/adr/0001-headless-wagtail-astro.md), and
|
|
[ADR-0002](docs/adr/0002-nginx-reverse-proxy.md) for the rationale.
|
|
|
|
## Prerequisites
|
|
|
|
- Docker Engine with Docker Compose v2.
|
|
- Ports `8080`, `4321`, and `8000` available on localhost.
|
|
- A local hosts-file entry mapping `azionelab.org` to `127.0.0.1`.
|
|
|
|
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
|
|
```
|
|
|
|
For local domain resolution, add this line to `/etc/hosts` using your normal system
|
|
administration workflow:
|
|
|
|
```text
|
|
127.0.0.1 azionelab.org
|
|
```
|
|
|
|
Open:
|
|
|
|
- public site: <http://azionelab.org:8080>
|
|
- Wagtail admin: <http://azionelab.org:8080/admin/>
|
|
- aggregate API: <http://azionelab.org:8080/api/site/home/>
|
|
|
|
Direct loopback ports `4321` and `8000` remain available for local diagnostics only.
|
|
|
|
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 all four services report healthy.
|
|
|
|
## Create an editor account
|
|
|
|
```bash
|
|
docker compose exec backend python manage.py createsuperuser
|
|
```
|
|
|
|
Sign in to Wagtail at <http://azionelab.org:8080/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 reverse-proxy 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 proxy
|
|
|
|
# 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 run --rm proxy nginx -t
|
|
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
|
|
├── nginx/ # Reverse-proxy virtual host
|
|
├── 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 TLS certificates, production-grade static/media
|
|
serving, off-host backups, monitoring, and a deployment-specific secret manager.
|