MyBlog/docs/superpowers/specs/2026-03-26-docker-deploy-design.md

Docker deployment (make up/down)

Context

• Project: VuePress v2 static blog (Vite).
• Goal: one-command production deployment and teardown via make up and make down.
• Hosting: root path /.
• Port mapping: host 6666 -> container 80.

Goals

• Provide a reproducible, production-grade deployment using Docker.
• Keep operator commands minimal (make up, make down).
• Ensure build failures fail fast and are visible.

Non-goals

• No development-mode container (vuepress-vite dev).
• No additional runtime dependencies besides Docker.
• No advanced orchestration (k8s, swarm).

Assumptions

• Docker Engine and Docker Compose v2 are available on the host.
• package-lock.json is present; builds use npm ci.

Proposed architecture

• Multi-stage Docker image:
  • Stage 1 (build): Node image installs dependencies and runs docs:build.
  • Stage 2 (run): Nginx serves the generated static files.
• docker-compose.yml manages a single service (e.g., myblog).
• Makefile wraps compose commands for consistent UX.

Components

Dockerfile

• Base images: node:20-alpine (build), nginx:1.25-alpine (run).
• Stage 1:
  • Workdir set to app root.
  • Copy package.json + package-lock.json, run npm ci.
  • Copy source and run npm run docs:build.
• Stage 2:
  • Copy src/.vuepress/dist/ to /usr/share/nginx/html.
  • Use default Nginx config for root /.

.dockerignore

• Exclude: node_modules, dist, src/.vuepress/dist, .git, *.log.

docker-compose.yml

• Service name: myblog.
• Build context: repository root.
• Image name: myblog:latest.
• Port mapping: 6666:80.
• Restart policy: unless-stopped.

Makefile

• make up: docker compose up -d --build.
• make down: docker compose down.
• Optional commands (if desired later): make logs, make ps, make rebuild.

Runtime flow

1. Operator runs make up.
2. Docker builds image (install deps -> build static site).
3. Nginx container starts and serves static files.
4. Operator runs make down to stop and remove the service.

Error handling

• Build failures (dependency install or VuePress build) cause make up to fail and exit.
• Compose output provides the error details for diagnosis.

Verification

• Access http://<host>:6666/ and confirm the site loads.
• Optional: docker compose logs -f for runtime inspection.

Security / operations

• No secrets are required.
• Container only exposes HTTP on port 80 inside the compose network.

Open questions

• None. All required inputs confirmed (production mode, root path, port 6666).