ADR-0002. Local Nginx route table for native-dev parity
| Field | Value |
|---|---|
| Status | Accepted |
| Date | 2025-01-20 |
| Deciders | @platform |
| Supersedes | — |
Context
- In native development services run directly on the host (
127.0.0.1:31xx), not in Docker — so Traefik's Docker-label discovery does not apply. - The frontend wants a single base URL (
http://sgw.local.bana.com.vn/v1/api) regardless of which service it calls, mirroring the production edge. - Running the full Docker/Traefik stack locally is heavy and slows the inner dev loop.
- Service prefixes already match
APP_ENV_SERVER_BASE_PATH, so no path rewriting is needed.
Decision
We will front native services with a single Nginx container (local-nx-gateway) using host networking, driven by an explicit central route table in local/nginx.conf (upstream blocks + location /v1/api/<svc>/ per service, plus /stream and /__gateway_health).
Consequences
| Pros | Cons |
|---|---|
| One stable base URL for the FE — matches prod edge behavior | Host networking is Linux-only |
| Lightweight — single container, no Traefik/Docker stack | Route table is manual: each new service needs an upstream + location edit |
Unmatched paths fail fast with a clear 404 JSON | Two route definitions to keep in sync (prod labels vs dev nginx.conf) |
WebSocket /stream and a health probe work locally | No resilience middlewares in dev (intentional — closer to raw service behavior) |
Alternatives Considered
| Option | Pros | Cons | Why rejected |
|---|---|---|---|
| Run Traefik locally too | Identical proxy to prod | Requires Docker-izing every dev service; heavy | Defeats the fast native-dev loop |
FE points directly at each 127.0.0.1:31xx | No gateway at all | Many base URLs; no prod parity; CORS pain | Poor DX, diverges from prod |
| Docker Compose dev stack with Traefik | Full parity | Slow rebuilds, resource-heavy | Inner-loop friction |
References
- Configuration — Local Nginx Route Table
packages/gateway/local/nginx.conf