Docker Composer

---
name: docker-composer
description: |
  Trigger when the user asks to set up Docker, write a Dockerfile, or create a
  docker-compose.yml. Phrases: "dockerize", "add Docker", "compose file",
  "Dockerfile", "multi-stage build".
allowed-tools:
  - Read
  - Write
  - Grep
  - Bash(docker *)
---

# Docker Composer

Produce a production-quality Dockerfile and docker-compose.yml for a web
application. Handles Node, Python, and Go projects.

## Prerequisites

- Project identifies its stack clearly via package.json, pyproject.toml, or go.mod
- Running locally with a known entry point

## Steps

1. **Detect the stack.** Check lockfiles and manifests:
   - `pnpm-lock.yaml` or `package-lock.json` -> Node
   - `pyproject.toml` or `requirements.txt` -> Python
   - `go.mod` -> Go

2. **Write a multi-stage Dockerfile.** Never ship a Dockerfile that copies
   the entire source tree into the final image.

   Node example (Next.js with pnpm):

   ```dockerfile
   FROM node:20-alpine AS deps
   WORKDIR /app
   COPY package.json pnpm-lock.yaml ./
   RUN corepack enable && pnpm install --frozen-lockfile

   FROM node:20-alpine AS builder
   WORKDIR /app
   COPY --from=deps /app/node_modules ./node_modules
   COPY . .
   RUN corepack enable && pnpm build

   FROM node:20-alpine AS runner
   WORKDIR /app
   ENV NODE_ENV=production
   COPY --from=builder /app/.next ./.next
   COPY --from=builder /app/public ./public
   COPY --from=builder /app/package.json ./
   COPY --from=deps /app/node_modules ./node_modules
   EXPOSE 3000
   CMD ["pnpm", "start"]
   ```

3. **Write docker-compose.yml** for local dev. Include:
   - App service with correct port mapping
   - Dependencies (Postgres, Redis) with pinned versions
   - Named volumes for persistence
   - `depends_on` with health checks, not just service order
   - Env from `.env`; never hardcode secrets

4. **Add a `.dockerignore`.** At minimum exclude:
   ```
   node_modules
   .next
   .git
   .env*
   *.log
   dist
   coverage
   ```

5. **Verify the build works:**
   ```bash
   docker compose build
   docker compose up
   curl -f http://localhost:3000/health
   ```

## Gotchas

- Using `node:20` instead of `node:20-alpine` or `node:20-slim` doubles image size.
- Forgetting to bind to `0.0.0.0` in the app means the port mapping does not work.
- `COPY . .` before `RUN npm ci` invalidates the dependency cache on every source change.

## Output

- Dockerfile (multi-stage)
- docker-compose.yml
- .dockerignore
- Image builds and runs, health check passes