plano/docs/ADR/003-single-container-supervisord.md

ADR 003: Single Container with Supervisord

Status: Accepted

Context

Plano has three runtime processes:

1. Envoy Proxy — the data plane with WASM filters
2. Brightstaff — the Rust HTTP service for routing and orchestration
3. Config generator — Python script that validates config and renders Envoy's YAML (runs at startup)

The options for deployment were:

1. Separate containers — each process in its own container, orchestrated by Docker Compose / K8s
2. Single container with process manager — all processes in one container, managed by Supervisord
3. Single binary — embed Envoy or reimplement its core functionality

Decision

Run all processes in a single container managed by Supervisord. The startup sequence:

1. Config generator validates arch_config.yaml and renders envoy.yaml
2. Supervisord starts Brightstaff and Envoy in parallel
3. A log tail process unifies access log output

Consequences

Enables:

• Simple deployment: one container, one image, docker run just works
• No network latency between Envoy and Brightstaff (localhost communication)
• Config generation happens at container startup — no external config rendering step
• Easy development: docker compose up with volume mounts for hot-reload

Requires:

• Supervisord configuration (config/supervisord.conf) to manage process lifecycle
• Health checks must account for both Envoy and Brightstaff readiness
• Logs from all processes need unified output (handled by the tail process)

Prevents:

• Independent scaling of Envoy vs. Brightstaff (they scale together as one unit)
• Kubernetes sidecar pattern (though this could be reconsidered)
• Process-level fault isolation (though Supervisord restarts failed processes)

Trade-off: Simplicity of deployment over horizontal scaling flexibility. For a gateway that needs to be deployed at the edge or as a sidecar, single-container simplicity is more valuable than the ability to scale components independently.