chore: add docker deployment support

2026-06-23 14:12:30 +08:00
parent 5b4c973812
commit f51f64f3bd
10 changed files with 449 additions and 0 deletions
@@ -0,0 +1,66 @@
+# Docker Configuration Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add low-download Docker configuration for production deployment and optional local development.
+
+**Architecture:** Build Vite output with the host's existing Node dependencies and serve it from a single small nginx image. Use a separate optional development image and compose file that runs Vite with host source mounts.
+
+**Tech Stack:** Docker, Docker Compose, nginx stable Alpine slim, Node 20 Alpine (optional development only), Vite, React.
+
+---
+
+### Task 1: Production Container
+
+**Files:**
+- Create: `.dockerignore`
+- Create: `Dockerfile`
+- Create: `nginx.conf`
+- Create: `docker-compose.yml`
+
+- [ ] **Step 1: Add Docker build ignores**
+
+Create `.dockerignore` with dependency folders, logs, git metadata, and local env files excluded. Keep `dist` in the build context because production copies the host-built output.
+
+- [ ] **Step 2: Add production Dockerfile**
+
+Create a single-stage Dockerfile using `nginx:stable-alpine3.23-slim` and copy the locally generated `dist` directory to `/usr/share/nginx/html`.
+
+- [ ] **Step 3: Add nginx fallback config**
+
+Create `nginx.conf` with `try_files $uri $uri/ /index.html;` so front-end routes refresh correctly.
+
+- [ ] **Step 4: Add production compose file**
+
+Create `docker-compose.yml` mapping host `8080` to container `80`. The API key is consumed by the host-side Vite build and is not passed into Docker.
+
+### Task 2: Development Container
+
+**Files:**
+- Create: `Dockerfile.dev`
+- Create: `docker-compose.dev.yml`
+
+- [ ] **Step 1: Add development Dockerfile**
+
+Create `Dockerfile.dev` with Node 20 Alpine, dependency installation, and `npm run dev` as the command.
+
+- [ ] **Step 2: Add development compose file**
+
+Create `docker-compose.dev.yml` mapping host `3000` to container `3000`, mounting the project directory, and preserving container `node_modules`.
+
+### Task 3: Documentation And Verification
+
+**Files:**
+- Modify: `README.md`
+
+- [ ] **Step 1: Document production commands**
+
+Add `npm run build`, `docker compose up --build -d`, the low-download rationale, and the `http://localhost:8080` URL.
+
+- [ ] **Step 2: Document development commands**
+
+Add `docker compose -f docker-compose.dev.yml up --build` and the `http://localhost:3000` URL.
+
+- [ ] **Step 3: Verify**
+
+Run `npm run lint`, `npm run build`, `docker compose config`, build the production image, and request the application over HTTP if Docker is available.
@@ -0,0 +1,32 @@
+# Docker Configuration Design
+
+## Goal
+
+Add Docker support for both production deployment and local development of the Vite React app, while making the default production path minimize Docker downloads.
+
+## Architecture
+
+Production builds the static app on the host using the already-installed npm dependencies, then uses a single-stage `nginx:stable-alpine3.23-slim` Dockerfile to copy and serve `dist` on port `80`. This avoids downloading a Node image and reinstalling npm packages during the Docker deployment.
+
+Development remains an optional separate Dockerfile and compose file. It installs dependencies, runs `npm run dev`, exposes Vite on port `3000`, and mounts source files from the host while keeping `node_modules` inside the container. It is not the low-download production path.
+
+## Files
+
+- `.dockerignore` excludes dependencies, unrelated build output, logs, and local env files from Docker build context, while retaining `dist` for the production image.
+- `Dockerfile` creates a small production image from the host-built static output.
+- `nginx.conf` serves static assets and falls back to `index.html` for React Router routes.
+- `docker-compose.yml` runs the production image on host port `8080`.
+- `Dockerfile.dev` runs the Vite dev server.
+- `docker-compose.dev.yml` runs the development container on host port `3000`.
+- `README.md` documents the Docker commands.
+
+## Environment
+
+The current Vite config injects `GEMINI_API_KEY` during build. Production therefore reads `.env.local` during the host-side `npm run build` command and copies the resulting static bundle into the container. Development reads environment values from `.env.local` when present.
+
+## Verification
+
+- Run `npm run lint`.
+- Run `npm run build`.
+- Build the production Docker image after a host-side `npm run build`.
+- Optionally run the compose services if Docker is available.