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.
• Convert the frontend to a static build served directly by Nginx.
• 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.

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 only the application port needed inside the compose network.
• nginx becomes the public entrypoint. It serves the built frontend assets and proxies /api/ and /health to the backend service.
• The frontend is no longer a long-running service in production. Its build artifacts are produced during the image build and copied into the Nginx image.

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 npm run dev, bind mounts, and exposed Vite ports.
• 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 must be handled by Nginx with try_files.
• Verification is done through docker compose config, image builds, container startup, and HTTP health checks.