bisco
2.4 KiB
ADR-0002: NGINX reverse proxy for the public virtual host
Date: 2026-06-24
Status: Accepted
TLS aspects of this decision are extended by ADR-0003.
Context
The Compose stack exposes Astro and Wagtail on separate local ports. Azione!Lab needs
one domain-aware HTTP entry point for azionelab.org while keeping application routing
and service discovery inside Docker Compose.
Decision
Add a pinned NGINX Alpine container. Its azionelab.org virtual host routes Wagtail
admin, API, documents, health, static files, and media to Django; all other paths go to
Astro. An explicit default virtual host returns 404 for unknown host names.
For local development NGINX binds to 127.0.0.1:8080, configurable through
NGINX_BIND_ADDRESS and NGINX_HTTP_PORT. Existing loopback-only application ports
remain available for diagnostics. PostgreSQL remains private to the Compose network.
TLS termination is outside this local implementation.
Consequences
- The preferred local URL becomes
http://azionelab.org:8080after a hosts-file entry. - Wagtail receives the original host and standard forwarded client/protocol headers.
- Media URLs must use the reverse-proxy address through
WAGTAILADMIN_BASE_URL. - Production deployment still requires TLS, trusted proxy policy, and removal or firewalling of diagnostic application ports.
Alternatives considered
- Routing only the frontend was rejected because Wagtail admin, API, and media should share the public domain.
- Replacing Astro or Django with static files served directly by NGINX was rejected as unnecessary for the requested local stack.
- Adding automatic certificates was initially deferred because DNS and certificate ownership were not part of this task; ADR-0003 later adds an opt-in implementation.
Security impact
Unknown host names are rejected. NGINX adds basic content-type and referrer headers, runs without added capabilities or privileged mode, and is bound to loopback by default. No TLS guarantee is made by this local configuration.
Operational impact
NGINX depends on healthy frontend and backend services and has its own health check. Operators must configure DNS/hosts, the public Wagtail base URL, and the published port.
Rollback
Remove the NGINX service and configuration, restore direct application URLs, and revert the related allowed-host and public-base-URL values. Database and media data are not changed.