Cheng Zhou
111 lines
3.6 KiB
Markdown
111 lines
3.6 KiB
Markdown
# 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
|