feat: build headless theatre laboratory website

docs/runbook.md

@@ -1,19 +1,35 @@
 # Runbook
 
-Operational runbook for this project.
+## Site shows fallback content
 
-## Common tasks
+1. Check `docker compose ps` and the backend health status.
+2. Request `http://localhost:8000/api/site/home/` directly.
+3. Inspect `docker compose logs backend postgres`.
+4. Verify `PUBLIC_CMS_API_URL` resolves from the frontend container.
+5. Restart the frontend after recovery so its static page is rebuilt from CMS data.
 
-Document routine operational tasks here.
+## Wagtail does not start
 
-## Troubleshooting
+1. Confirm PostgreSQL is healthy.
+2. Check `DATABASE_URL` and allowed hosts without printing secret values in shared logs.
+3. Run `docker compose exec backend python manage.py migrate`.
+4. Review backend logs for a specific migration or configuration error.
 
-Document known issues, symptoms, checks, and remediation steps.
+## Images are missing
+
+1. Verify the `media_data` volume is mounted at `/app/media`.
+2. Check `WAGTAILADMIN_BASE_URL` uses a URL reachable by the browser.
+3. Confirm the image still exists in Wagtail and has not been removed from the volume.
+
+## A service is unhealthy
+
+1. Run `docker compose ps` and inspect `docker compose logs --tail=200 SERVICE`.
+2. For PostgreSQL, check volume capacity and database/user configuration.
+3. For the backend, check `/health/`, migrations, and database connectivity.
+4. For the frontend, request port `4321`, then check the API separately because
+   fallback content can mask a CMS outage.
 
 ## Rollback
 
-Document rollback procedures here.
-
-## Emergency contacts
-
-Document project-specific escalation paths if appropriate.
+Revert the application commit and rebuild containers. Preserve database/media volumes.
+Before reversing migrations or deleting volumes, make and validate coordinated backups.