AgentBlock/docs/superpowers/plans/2026-05-13-docker-configuration.md

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.