generated from bisco/codex-bootstrap
bisco
60 lines
2.4 KiB
Markdown
60 lines
2.4 KiB
Markdown
# 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](0003-optional-letsencrypt.md).
|
|
|
|
## 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:8080` after 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.
|