# 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.