Back to MusePages

Historic Atlas — One origin, clear routes

The original prompt, shown in full as plain text.

Prompt

# SPEC: Ingress web server

Status: draft. Part of [SPEC.md](../SPEC.md).

## Purpose

Define the web server that sits in front of the partial applications.

## Requirements

- Clients reach the frontend, the backend API and the Keycloak endpoints only
  through this web server.
- It routes requests to the right partial application.
- TLS is terminated in front of it (see
  [SPEC-deployment.md](SPEC-deployment.md)).

## Decisions

Decided in [AVARC-8](../tasks/finished/TASK-ingress-decision.md).

- **Product:** nginx, changed from Caddy in
  [AVARC-33](../tasks/finished/TASK-ingress-image.md) (which first chose Caddy,
  [AVARC-8](../tasks/finished/TASK-ingress-decision.md)). nginx is a web
  server of the Paketo buildpacks, so the ingress image is built with
  `pack` like the backend and the frontend, through the shared build
  configuration, from the configuration file `nginx.conf` alone; Caddy has
  no buildpack. The configuration is in the module `avarc-server-ingress`
  and is part of the image; the nginx version is the one the buildpack
  selects. The image listens on port 8080 and runs as the unprivileged user
  of the buildpack run image. The upstreams (`backend`, `frontend`,
  `keycloak`) are looked up per request through Docker's resolver, so a
  restarted service is found again and the ingress starts before they do.
- **URL layout:** one host with path prefixes, so the browser sees a single
  origin (no CORS, simple cookie sessions):
  - `/api/` routes to the backend.
  - `/actuator/` routes to the backend's actuator, which is on a port of its
    own (see [SPEC-backend.md](SPEC-backend.md)), but only where the
    variable `ACTUATOR_ENABLED` of the ingress is `true` (development and
    stage, where `run.sh` sets it with the developer links); elsewhere the
    ingress answers 404. The nginx configuration reads it when the container
    starts, so the image is the same everywhere.
  - `/auth/` routes to the public endpoints of Keycloak (login, logout,
    token and account pages), without prefix stripping; which of its paths
    are routed is defined in [SPEC-auth.md](SPEC-auth.md).
  - everything else routes to the frontend, including its `/health` (status
    only).
  - The prefixes are reserved and are not used by frontend pages. A
    post-MVP MCP server gets its own prefix when it is taken up.
- **Authentication:** the ingress only routes and forwards requests,
  including the session credentials, unchanged. It does not enforce
  authentication; the backend validates the session or identity of every
  non-public request, as required by [SPEC-auth.md](SPEC-auth.md). This
  keeps a single enforcement point. AVARC-13 confirmed this.

- **Forwarded headers:** TLS is terminated before the ingress (see
  [SPEC-deployment.md](SPEC-deployment.md)), so the ingress trusts the
  forwarded headers of private-range hops and passes them on unchanged;
  the upstreams see the original scheme and host, which Keycloak needs for
  secure cookies. For a hop that is not trusted, the headers are replaced by
  the values of the connection.

- **Request ID and access log** ([AVARC-24](../tasks/TASK-observability-ingress-database.md),
  conventions in [SPEC-observability.md](SPEC-observability.md)): every
  request gets an ID, sent to the upstreams and back to the client in the
  header `X-Request-Id`. A valid value (8 to 64 characters of letters,
  digits, `.`, `_`, `-`) from a trusted hop is kept; from anywhere else it is
  replaced. The access log is one JSON object per line on standard output
  with the shared fields, the path without the query string (it can carry
  login codes), the status, the sizes and the durations, and never cookies or
  authorization headers. nginx's own error log stays plain text on standard
  error.
- **Metrics:** a second listener on port 8081 serves nginx's `stub_status`
  to the metrics exporter of the Compose project. The port is not
  published, and the public listener does not route to it.

## Open questions

- Caching, compression and rate limiting.