Stage 1: Build

Multi-Stage Builds

Node.js Application

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

# Stage 2: Production
FROM node:20-alpine AS runner
WORKDIR /​app
ENV NODE_ENV=production

# Create non-root user
RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 appuser

COPY --from=builder /​app/​dist ./​dist
COPY --from=builder /​app/​node_modules ./​node_modules
COPY --from=builder /​app/​package.json ./

USER appuser
EXPOSE 3000
CMD ["node", "dist/​index.js"]

Python Application

# Stage 1: Build
FROM python:3.12-slim AS builder
WORKDIR /​app
RUN pip install --no-cache-dir poetry
COPY pyproject.toml poetry.lock ./
RUN poetry export -f requirements.txt > requirements.txt
RUN pip wheel --no-cache-dir --wheel-dir /​wheels -r requirements.txt

# Stage 2: Production
FROM python:3.12-slim AS runner
WORKDIR /​app

RUN useradd --create-home appuser
COPY --from=builder /​wheels /​wheels
RUN pip install --no-cache /​wheels/​*

COPY . .
USER appuser
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0"]

---

Layer Caching

Optimize Build Order

# GOOD: Dependencies change less often than code
COPY package*.json ./
RUN npm ci                # Cached if package.json unchanged
COPY . .                   # Only this layer rebuilds on code change
RUN npm run build

# BAD: Code change invalidates npm install cache
COPY . .
RUN npm ci
RUN npm run build

Use .dockerignore

# .dockerignore
node_modules
npm-debug.log
dist
.git
.env
*.md
.DS_Store

---

Docker Compose

Development Stack

# docker-compose.yml
version: '3.8'

services:
  app:
    build: 
      context: .
      target: builder  # Use builder stage for dev
    volumes:
      - .:/​app
      - /​app/​node_modules  # Don't override node_modules
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://postgres:postgres@db:5432/​app
    depends_on:
      db:
        condition: service_healthy
    command: npm run dev

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: app
    volumes:
      - postgres_data:/​var/​lib/​postgresql/​data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/​data

volumes:
  postgres_data:
  redis_data:

Production Override

# docker-compose.prod.yml
version: '3.8'

services:
  app:
    build:
      target: runner  # Use production stage
    volumes: []       # No code mounting
    environment:
      - NODE_ENV=production
    restart: unless-stopped

# Development
docker-compose up

# Production
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d

---

Health Checks

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

# docker-compose.yml
services:
  app:
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/​health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s

---

Security Best Practices

Run as Non-Root

RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser

USER appuser

Read-Only Filesystem

services:
  app:
    read_only: true
    tmpfs:
      - /​tmp

Minimal Base Images

# Prefer
FROM node:20-alpine       # ~50MB
FROM python:3.12-slim     # ~120MB

# Avoid for production
FROM node:20              # ~1GB
FROM ubuntu:22.04         # ~70MB + your deps

Scan for Vulnerabilities

# Using Docker Scout
docker scout cves myimage:latest

# Using Trivy
trivy image myimage:latest

---

Common Patterns

Wait for Dependencies

services:
  app:
    depends_on:
      db:
        condition: service_healthy

Or use a script:

#!/​bin/​sh
# wait-for-db.sh
until pg_isready -h db -U postgres; do
  echo "Waiting for database..."
  sleep 2
done
exec "$@"

Environment Variables

services:
  app:
    environment:
      - DATABASE_URL=${DATABASE_URL}  # From .env file
    env_file:
      - .env.local

Secrets Management

services:
  app:
    secrets:
      - db_password

secrets:
  db_password:
    file: ./​secrets/​db_password.txt

---

Common Gotchas

PID 1 Signal Handling

Use exec form of CMD or use tini:

# GOOD: exec form receives signals properly
CMD ["node", "dist/​index.js"]

# Or use tini
RUN apk add --no-cache tini
ENTRYPOINT ["/​sbin/​tini", "--"]
CMD ["node", "dist/​index.js"]

node_modules in Volumes

Anonymous volume prevents host node_modules from overriding:

volumes:
  - .:/​app
  - /​app/​node_modules  # Anonymous volume

Build Context Size

Large contexts slow builds. Use .dockerignore.

Layer Order Matters

Less frequently changed files first → better cache utilization.

---

Quick Reference

References

• Dockerfile Best Practices
• Docker Compose Docs