# Docker Patterns

> When to activate: Dockerfile, docker-compose, container, image build, multi-stage, docker run, healthcheck, .dockerignore

- Skill: `mattakushi432/docker-patterns` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mattakushi432/docker-patterns`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mattakushi432/docker-patterns/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Mattakushi432 (https://skillmd.com/u/mattakushi432)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mattakushi432/docker-patterns

---

# Docker Patterns

## Multi-Stage Build (Go example)

```dockerfile
FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /bin/app ./cmd/server

FROM gcr.io/distroless/static-debian12
COPY --from=builder /bin/app /app
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app"]
```

## Multi-Stage Build (Node.js)

```dockerfile
FROM node:20-alpine AS deps
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
COPY --from=deps /app/node_modules ./node_modules
COPY --from=builder /app/dist ./dist
USER node
EXPOSE 3000
CMD ["node", "dist/index.js"]
```

## .dockerignore

```
node_modules
.git
.env
.env.*
*.log
dist
coverage
.DS_Store
Dockerfile*
docker-compose*
README.md
```

## Layer Caching — copy deps first

```dockerfile
# GOOD: dependencies layer cached unless package.json changes
COPY package*.json ./
RUN npm ci
COPY . .

# BAD: every code change busts the npm ci layer
COPY . .
RUN npm ci
```

## Health Check

```dockerfile
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:8080/health || exit 1
```

## docker-compose.yml

```yaml
services:
  app:
    build:
      context: .
      target: runner
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=${DATABASE_URL}
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - backend

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: ${DB_USER}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${DB_USER}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

  redis:
    image: redis:7-alpine
    command: redis-server --appendonly yes
    volumes:
      - redis_data:/data
    networks:
      - backend

volumes:
  pg_data:
  redis_data:

networks:
  backend:
    driver: bridge
```

## Resource Limits

```yaml
services:
  app:
    deploy:
      resources:
        limits:
          cpus: "0.5"
          memory: 512M
        reservations:
          cpus: "0.25"
          memory: 256M
```

## Key Rules
- Never run as root — add `USER nonroot` or `USER node`
- Pin base image digests in production: `node:20-alpine@sha256:...`
- Use `COPY --chown=user:user` instead of `RUN chown` (avoids extra layer)
- `CMD` vs `ENTRYPOINT`: use ENTRYPOINT for the binary, CMD for default args
- `RUN --mount=type=cache` speeds up package manager installs in BuildKit