ctms/docs/plans/2026-03-27-production-compose-design.md

Production Compose Design

Goal: Convert the current single-host docker-compose deployment from a development-oriented stack into a production-oriented stack while keeping the existing docker-compose.yaml as the only deployment entrypoint.

Decisions

• Keep single-host docker-compose deployment.
• Keep the frontend as an independently deployable runtime image.
• Keep PostgreSQL and the existing pg_data persistence model.
• Keep one backend container and remove development-only runtime behavior.
• Update the existing docker-compose.yaml in place instead of introducing a separate production file.
• Leave public ingress to an external reverse proxy outside this repository.

Architecture

• db remains a long-lived PostgreSQL service with the existing bind-mounted data directory.
• backend runs from the backend image default command and exposes port 8000.
• frontend runs from its own image and serves the SPA on a dedicated frontend port.
• An external reverse proxy becomes the public entrypoint and routes browser traffic to frontend and API traffic to backend.

Cleanup Scope

• Remove development-only compose services such as toolbox/init containers.
• Remove development-only backend startup overrides such as debugpy and uvicorn --reload.
• Remove development-only frontend runtime behavior such as bind mounts and hot-reload-only startup behavior.
• Keep data persistence and core service names stable where practical to limit operational change.

Operational Notes

• Updating docker-compose.yaml in place means local development will no longer use the previous hot-reload setup by default.
• Frontend SPA routing and same-origin /api behavior must be handled by the external reverse proxy.
• Verification is done through docker compose config, image builds, container startup, and direct HTTP health checks.