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

Production Compose Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Convert the repository's only docker-compose.yaml from development deployment to production deployment using static frontend assets served by Nginx.

Architecture: The backend runs as a production FastAPI container, the frontend is built into static assets during image build, and Nginx serves the SPA while reverse proxying backend routes. PostgreSQL remains persistent through the existing pg_data bind mount.

Tech Stack: Docker Compose, FastAPI, Vue/Vite, Nginx, PostgreSQL

---

Task 1: Productionize Frontend Image

Files:

• Modify: frontend/Dockerfile

Step 1: Replace dev runtime with a multi-stage production build

Update the Dockerfile so a Node build stage runs dependency install and npm run build, then a lightweight stage exposes the built dist directory for downstream use instead of running npm run dev.

Step 2: Keep the output suitable for Nginx consumption

Ensure the final stage stores frontend assets in a predictable directory such as /usr/share/nginx/html.

Step 3: Verify the image definition is syntactically valid

Run: docker compose config Expected: compose renders successfully with no Dockerfile-related errors.

Task 2: Productionize Nginx Runtime

Files:

• Modify: nginx/nginx.conf

Step 1: Add static frontend serving

Set the web root to the built frontend assets and add try_files $uri $uri/ /index.html; for SPA routing.

Step 2: Keep backend reverse proxy behavior

Preserve /api/ and /health proxying to backend:8000 with standard forwarded headers.

Step 3: Verify config structure through compose-backed startup

Run: docker compose config Expected: compose renders successfully.

Task 3: Productionize Compose Topology

Files:

• Modify: docker-compose.yaml

Step 1: Remove dev-only services and settings

Delete frontend, frontend-init, and backend-init, and remove bind mounts, debug ports, and development commands that are only useful for hot reload or scaffolding.

Step 2: Wire backend and nginx for production

Allow the backend to use its Dockerfile default command, keep the database dependency, and expose only the ports needed for the production stack.

Step 3: Build frontend assets into nginx

Point the Nginx service build to a production image definition that includes the built frontend output.

Step 4: Verify rendered compose

Run: docker compose config Expected: only the production services remain and configuration renders cleanly.

Task 4: Add Deployment Verification

Files:

• Modify: README.md

Step 1: Update deployment entry description

Document that docker-compose.yaml is now the production deployment entrypoint.

Step 2: Add minimal verification commands

Document docker compose up -d --build, plus health checks for / and /health.

Step 3: Verify behavior

Run: docker compose up -d --build Expected: db, backend, and nginx start successfully.

Task 5: End-to-End Verification

Files:

• Verify only

Step 1: Render final compose

Run: docker compose config Expected: PASS

Step 2: Start stack

Run: docker compose up -d --build Expected: PASS

Step 3: Check HTTP endpoints

Run: curl -i http://127.0.0.1/ Expected: 200 OK and HTML payload

Run: curl -i http://127.0.0.1/health Expected: successful backend health response