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