Add container deployment model (ADR-020) and fix review issues

- ADR-020: Document defense-in-depth rationale for running in a minimal
  Docker container (memory-safe language + container isolation), flexible
  upstream addressing (Docker DNS, loopback, LAN, tunnel endpoints),
  file-primary logging for fail2ban, and volume mount strategy
- ADR-016: Add allow_wildcard_bind override for container deployments
  where 0.0.0.0 is correct inside the container network namespace
- operations.md: Add container deployment section with Docker Compose
  example, networking table, volume mounts, and health check integration;
  flip logging to file-primary for fail2ban reliability; note systemd as
  alternative to container deployment
- config.md: Restructure logging fields into nested LoggingConfig (matching
  TOML [logging] section), add allow_wildcard_bind, shutdown_timeout_secs,
  and log_file_path fields; clarify upstream addressing supports Docker
  DNS and tunnel endpoints; update validation rule for 0.0.0.0 override
- overview.md: Update architecture diagram for container model with Docker
  networking and volume mounts; add ADR-020 reference
- proxy.md: Clarify X-Forwarded-Proto is determined by listener port, not
  hardcoded 80/443
- ADR-013: Fix health_check_port default contradiction (default is 9900,
  not 0/disabled as previously stated)
This commit is contained in:
2026-06-11 10:10:32 +00:00
parent 346754fb2b
commit fecc385d75
8 changed files with 385 additions and 48 deletions

View File

@@ -19,8 +19,15 @@ deployment.
## Decision
The `bind_addr` field on each `[[listeners]]` entry must be an explicit IP
address. `0.0.0.0` is rejected during config validation. The proxy will not
start if any listener's `bind_addr` is `0.0.0.0`.
address. `0.0.0.0` is rejected during config validation unless explicitly
overridden. The proxy will not start if any listener's `bind_addr` is
`0.0.0.0` and the override is not enabled.
**Override mechanism**: `allow_wildcard_bind = true` in the config file, or
`--allow-wildcard-bind` on the command line. This flag permits `0.0.0.0` as a
valid bind address. It is intended for container deployments where the
container's network namespace is isolated and `0.0.0.0` is the correct address
(Docker publishes only the explicitly mapped ports).
## Rationale
@@ -31,24 +38,31 @@ start if any listener's `bind_addr` is `0.0.0.0`.
- `0.0.0.0` is often a default in example configurations and can be deployed
without the operator realizing the service is accessible on all interfaces
- Rejecting it at validation time prevents this common mistake
- If a deployment genuinely needs to bind all interfaces, `0.0.0.0` can be
overridden with an explicit flag, but this should be a deliberate choice
- In a container, `0.0.0.0` is correct and safe because the container's
network namespace isolates it — only Docker-published ports are reachable
from outside the container
- The override is opt-in so it must be a deliberate choice, not an accident
- This matches the principle of explicit over implicit for security-sensitive
configuration
## Consequences
**Positive:**
- Prevents accidental exposure on unintended network interfaces
- Prevents accidental exposure on unintended network interfaces in bare-metal
deployments
- Forces operators to be deliberate about which interface the proxy serves
- Config validation catches the mistake before deployment
- Container deployments work correctly with `0.0.0.0` when the override is
explicitly enabled
**Negative:**
- Not suitable for deployments that genuinely need to bind all interfaces
(mitigated by explicit override if needed in the future)
- Slightly more configuration required (operator must know their public IP)
- Container deployments require one extra config flag (`allow_wildcard_bind =
true`) — a minor operational step
- Slightly more configuration required for bare-metal (operator must know
their public IP)
## References
- [ADR-020: Container Deployment Model](020-container-deployment.md)
- [config.md](../config.md)
- [overview.md](../overview.md)