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 standalone frontend and backend runtime images.

Architecture: The backend runs as a production FastAPI container, the frontend is built into a standalone runtime image that serves the SPA itself, and an external reverse proxy routes browser and API traffic to the correct container. PostgreSQL remains persistent through the existing pg_data bind mount.

Tech Stack: Docker Compose, FastAPI, Vue/Vite, Node.js, 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 frontend runtime consumption

Ensure the final stage stores frontend assets in a predictable directory and starts a static server on a stable port.

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 Frontend Runtime

Files:

• Modify: frontend/Dockerfile

Step 1: Add static frontend serving

Use the runtime image to expose a frontend port and serve the compiled SPA directly.

Step 2: Leave reverse proxy behavior to external infrastructure

Do not embed repository-owned reverse proxy configuration; document that / routes to frontend and /api plus /health route to backend.

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 frontend 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: Add standalone frontend service

Point the frontend service build to frontend/Dockerfile and give it a registry-backed image reference.

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 direct health checks for the frontend and backend containers.

Step 3: Verify behavior

Run: docker compose up -d --build Expected: db, backend, and frontend 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:4173/ Expected: 200 OK and HTML payload

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