docker-patterns

Docker Patterns

Best practices for building secure, efficient, and production-ready Docker images and compositions.

Multi-Stage Builds

Multi-stage builds separate build dependencies from runtime, producing smaller and more secure images.

Node.js / TypeScript

# Stage 1: Install dependencies
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts

# Stage 2: Build
FROM node:20-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build
RUN npm prune --production

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

RUN addgroup -g 1001 appgroup && \
    adduser -u 1001 -G appgroup -s /bin/sh -D appuser

COPY --from=build --chown=appuser:appgroup /app/dist ./dist
COPY --from=build --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=build --chown=appuser:appgroup /app/package.json ./

USER appuser
EXPOSE 3000

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/index.js"]

Python

# Stage 1: Build
FROM python:3.12-slim AS build
WORKDIR /app

RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

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

RUN groupadd -r appgroup && useradd -r -g appgroup -s /sbin/nologin appuser

COPY --from=build /opt/venv /opt/venv
COPY --from=build --chown=appuser:appgroup /app .

ENV PATH="/opt/venv/bin:$PATH"
USER appuser
EXPOSE 8000

HEALTHCHECK --interval=30s --timeout=3s --start-period=10s --retries=3 \
  CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1

CMD ["gunicorn", "--bind", "0.0.0.0:8000", "--workers", "4", "app:create_app()"]

Go

# Stage 1: Build
FROM golang:1.22-alpine AS build
WORKDIR /app

COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o /server ./cmd/server

# Stage 2: Production (scratch = no OS, minimal attack surface)
FROM scratch AS production

COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=build /server /server

USER 65534:65534
EXPOSE 8080

ENTRYPOINT ["/server"]

Layer Caching Optimization

Docker caches each layer. Order instructions from least-frequently-changed to most-frequently-changed.

Layer Order (Top = Changes Least)

# 1. Base image              (changes: rarely)
FROM node:20-alpine

# 2. System dependencies     (changes: rarely)
RUN apk add --no-cache dumb-init

# 3. Create user             (changes: never)
RUN adduser -D appuser

# 4. Working directory        (changes: never)
WORKDIR /app

# 5. Package manifests       (changes: occasionally)
COPY package.json package-lock.json ./

# 6. Install dependencies    (changes: occasionally, cached if manifests unchanged)
RUN npm ci

# 7. Application code        (changes: frequently)
COPY . .

# 8. Build step              (changes: frequently)
RUN npm run build

# 9. Runtime config          (changes: rarely)
USER appuser
CMD ["node", "dist/index.js"]

Caching Rules

| Rule | Why | |------|-----| | Copy lock files before source code | Dependency install is cached if lock file unchanged | | Use npm ci not npm install | Deterministic installs, respects lock file exactly | | Use --no-cache-dir for pip | Avoids storing pip cache in the layer | | Combine RUN commands with && | Fewer layers, smaller image | | Use .dockerignore | Prevents cache busting from irrelevant file changes |

What Busts the Cache

| Change | Layers Invalidated | |--------|-------------------| | Edit source code | Code COPY and everything after | | Edit package.json | Dependency install and everything after | | Change base image tag | Everything | | Add a new RUN before existing ones | That RUN and everything after |

Security Hardening

Non-Root User (Required)

Never run containers as root. A compromised container running as root can escalate to host-level access.

# Alpine
RUN addgroup -g 1001 appgroup && \
    adduser -u 1001 -G appgroup -s /bin/sh -D appuser
USER appuser

# Debian/Ubuntu
RUN groupadd -r appgroup && useradd -r -g appgroup -s /sbin/nologin appuser
USER appuser

# Scratch (numeric user, no user database)
USER 65534:65534

Minimal Base Images

| Base Image | Size | Use Case | |-----------|------|----------| | scratch | 0 MB | Statically compiled Go binaries | | alpine | ~5 MB | Most applications | | distroless | ~20 MB | When you need glibc but not a shell | | slim | ~80 MB | When alpine causes compatibility issues | | full | ~900 MB | Never in production |

Secrets Management

NEVER put secrets in these locations:

| Location | Why It Is Dangerous | |----------|-------------------| | ENV instruction | Visible in docker inspect, image history, and all child images | | ARG instruction | Visible in build history (docker history) | | COPY-ed files | Persists in image layer even if deleted in later layer | | Build context | Accessible during build if not in .dockerignore |

Safe alternatives:

# Runtime secrets via environment variables (set at run time, not build time)
# docker run -e DATABASE_URL=... myapp

# Docker secrets (Swarm/Compose)
# docker secret create db_password ./password.txt

# Mount secrets at build time (BuildKit, not persisted in layers)
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci

Security Checklist

• [ ] Running as non-root user
• [ ] Using minimal base image (alpine/distroless/scratch)
• [ ] No secrets in ENV, ARG, or COPY instructions
• [ ] No secrets in build context (check .dockerignore)
• [ ] Pinned base image versions (not latest)
• [ ] --no-cache-dir on package installs
• [ ] Read-only filesystem where possible (--read-only flag)
• [ ] No unnecessary packages installed
• [ ] Health check configured
• [ ] Dropped all Linux capabilities not needed (--cap-drop=ALL)

Image Scanning

Scan images for known vulnerabilities before deploying.

# Docker Scout (built into Docker Desktop)
docker scout cves myimage:latest

# Trivy (open source)
trivy image myimage:latest

# Snyk
snyk container test myimage:latest

Health Checks

Dockerfile HEALTHCHECK

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

Parameters

| Parameter | Default | Description | |-----------|---------|-------------| | --interval | 30s | Time between checks | | --timeout | 30s | Max time for a check to complete | | --start-period | 0s | Grace period for container startup | | --retries | 3 | Consecutive failures before unhealthy |

Health Check Commands by Stack

| Stack | Command | |-------|---------| | Node.js | wget --spider http://localhost:3000/health | | Python | python -c "import urllib.request; urllib.request.urlopen('http://...')" | | Go | Binary built with health endpoint | | Nginx | curl -f http://localhost/ \|\| exit 1 | | PostgreSQL | pg_isready -U postgres | | Redis | redis-cli ping |

Health Endpoint Best Practices

• Return 200 for healthy, 503 for unhealthy
• Check downstream dependencies (database, cache) in the health endpoint
• Keep checks fast (< 1 second)
• Separate liveness (is the process alive?) from readiness (can it serve traffic?)

Docker Compose Patterns

Development Compose

# compose.yaml (development)
services:
  app:
    build:
      context: .
      target: deps  # Stop at dependency stage for dev
    volumes:
      - .:/app
      - /app/node_modules  # Prevent host node_modules from overriding
    ports: