azionelab-v2/docs/operations.md

Operations

Routine commands

docker compose up --build -d
docker compose ps
docker compose logs -f proxy backend frontend db
docker compose down

Compose health checks all services. Through the virtual host, the public health endpoint is http://azionelab.org:8080/health/; the aggregate content endpoint is http://azionelab.org:8080/api/site/home/.

Test routing without changing the hosts file:

curl --resolve azionelab.org:8080:127.0.0.1 http://azionelab.org:8080/health/

Apply schema changes with docker compose exec backend python manage.py migrate. Create editors with createsuperuser; use Wagtail permissions for later non-superuser accounts.

The backend applies migrations at container startup. To permanently reset local state, use docker compose down --volumes; this deletes database, media, ACME challenges, and certificate state.

Certificate operations

With LETSENCRYPT_ENABLED=1, Certbot checks the certificate every 12 hours by default and renews it when due. NGINX checks the read-only certificate volume every 30 seconds and reloads only after its configuration validates. Adjust these intervals only for a documented operational reason.

docker compose ps -a certbot proxy
docker compose logs --tail=200 certbot proxy
docker compose run --rm --no-deps --entrypoint certbot certbot certificates

Certificate state is stored in letsencrypt_data; include it in protected host backups if recovery must preserve the same private key. Never copy its content into the repository or general application logs. When TLS is terminated by a load balancer, keep the service disabled and manage certificates at that edge instead.

Backup and restore

Back up the database and media at the same logical point in time:

mkdir -p backups/media
docker compose stop frontend backend
docker compose exec -T db 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

Restore is destructive: verify the backup in a disposable environment and take a fresh backup first. Then stop both applications, recreate and restore the database, replace the media content, restart, and verify health, API, admin login, and several images. Keep real backups encrypted and off-host with a defined retention policy.

Known risks

• Frontend fallback content can mask a CMS outage, so monitor backend health directly.
• Local named volumes are not off-host backups.
• Development media serving is unsuitable for production traffic.
• Automatic issuance depends on public DNS, inbound port 80, Let's Encrypt availability, and its rate limits. Test with the staging CA first.
• Deleting letsencrypt_data loses certificate account/key state and triggers a new issuance attempt when the service is enabled again.