azionelab-v2/docs/adr/0001-headless-wagtail-astro.md

ADR-0001: Headless Wagtail with an Astro frontend

Date: 2026-06-22

Status: Accepted

Context

The theatre workshop needs an editorially polished public single page whose core content can be updated without code changes. The required stack is Wagtail/Django, Astro, PostgreSQL, and Docker Compose. A small team must be able to run and maintain the system locally without unnecessary services.

Decision

Use Wagtail as a headless CMS backed by PostgreSQL and Astro as the public frontend. Wagtail owns uploaded media and exposes a read-only aggregate endpoint at /api/site/home/. Astro renders the page server-side in development/build time and uses curated Italian fallback content when the CMS is temporarily unavailable. Docker Compose runs PostgreSQL, Django, and Astro on one private default network.

The content model uses one Wagtail HomePage with three ordered feature cards, site settings, and reusable snippets for teacher details, lesson details, shows, and gallery items. This keeps editing simple and avoids a custom frontend state layer.

Consequences

• Editors use the authenticated Wagtail admin while the public API remains read-only.
• The public page needs only one API request and degrades gracefully during CMS outages.
• Uploaded media and PostgreSQL data require separate persistent volumes and backups.
• Local frontend rendering depends on container networking; browser-facing media URLs are generated from the configured public Wagtail base URL.

Alternatives considered

• Calling the standard Wagtail endpoints separately was rejected because it adds frontend orchestration for a single page.
• Embedding the frontend in Django templates was rejected because Astro is required.
• A JavaScript SPA and client-side state library were rejected as unnecessary.

Security impact

The aggregate endpoint exposes published editorial content only. Wagtail admin keeps its normal authentication and CSRF protections. Services bind to loopback for local development, containers are not privileged, and secrets are supplied through the environment.

Operational impact

Operators must back up the PostgreSQL and media volumes. CMS schema changes require normal Django migrations. Health checks order local startup.

Rollback

Revert the feature commit and remove the Compose volumes only if their stored content is no longer needed. Keep database and media backups when rolling back code alone.