/docker-templates

name: docker-templates
description: "Docker multi-stage build templates, image security, and docker-compose patterns. TRIGGER when: writing a Dockerfile, composing services, or hardening a container image. SKIP: CI pipeline definitions (use github-actions-template); runtime monitoring (use monitoring-observability)."

Multi-stage Build Pattern

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production=false
COPY . .
RUN npm run build

# Production stage
FROM node:20-alpine AS production
WORKDIR /app

# Security: Non-root user
RUN addgroup -g 1001 -S nodejs && \
    adduser -S nextjs -u 1001

# Copy only production artifacts
COPY --from=builder --chown=nextjs:nodejs /app/dist ./dist
COPY --from=builder --chown=nextjs:nodejs /app/node_modules ./node_modules
COPY --from=builder --chown=nextjs:nodejs /app/package.json ./

USER nextjs
EXPOSE 3000

# Health check
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

CMD ["node", "dist/server.js"]

Docker Security Best Practices

| Practice | Implementation | |----------|----------------| | Non-root user | `USER nodejs` after setup | | Minimal base image | Use `-alpine` variants | | No secrets in image | Use runtime env vars | | Pin versions | `FROM node:20.10.0-alpine` | | .dockerignore | Exclude node_modules, .git, .env | | Read-only filesystem | `--read-only` flag when possible | | Resource limits | Set memory/CPU limits |

Docker Compose Patterns

version: '3.8'

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      target: production
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - DATABASE_URL=${DATABASE_URL}
    depends_on:
      db:
        condition: service_healthy
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

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

volumes:
  postgres_data:

Image Size Targets

| App Type | Target Size | Strategy | |----------|-------------|----------| | Python API | < 200MB | `python:3.12-slim` + multi-stage | | Node.js API | < 150MB | `node:20-alpine` + multi-stage | | Go binary | < 50MB | `golang:1.21-alpine` build, `scratch` runtime |

Health Check Configuration

| Setting | Recommended | |---------|-------------| | Interval | 30s | | Timeout | 10s | | Retries | 3 | | Start period | 30s |

Return 200 for healthy, 503 for unhealthy. Keep checks lightweight.

Environment Variable Hierarchy

1. Runtime environment variables (highest priority) 2. `.env` file 3. `docker-compose.yml` defaults 4. Dockerfile `ENV` defaults (lowest)

Provide `.env.example` with placeholders (committed). Never commit `.env` files with secrets.

Resource Limits

| Resource | Development | Production | |----------|-------------|------------| | Memory | 512MB | Based on app profiling | | CPU | 0.5 | Based on app profiling |

Always set memory limits. Log to stdout/stderr, never to files inside containers.

Bundled References

Usable templates in `references/` based on actual project patterns:

| File | Description | |------|-------------| | `references/Dockerfile.react` | React + nginx multi-stage build (node:22-alpine build, nginx:alpine prod) | | `references/Dockerfile.python` | FastAPI multi-stage build (python:3.11-slim, uvicorn) | | `references/docker-compose.example.yml` | Minimal FastAPI + Postgres + Redis stack |

Copy and adapt these templates for new services. All include health checks, non-root users, and alpine base images.