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
Image Scanning
Scan images for known vulnerabilities before deploying.
docker scout cves myimage:latest
trivy image myimage:latest
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
services:
app:
build:
context: .
target: deps
volumes:
- .:/app
- /app/node_modules
ports:
- "3000:3000"
environment:
- NODE_ENV=development
depends_on:
db:
condition: service_healthy
command: npm run dev
db:
image: postgres:16-alpine
volumes:
- pgdata:/var/lib/postgresql/data
environment:
POSTGRES_DB: myapp_dev
POSTGRES_USER: devuser
POSTGRES_PASSWORD: devpassword
ports:
- "5432:5432"
healthcheck:
test: ["CMD-SHELL", "pg_isready -U devuser -d myapp_dev"]
interval: 5s
[, , ]
Production Compose
services:
app:
build:
context: .
target: production
restart: unless-stopped
ports:
- "3000:3000"
environment:
- NODE_ENV=production
env_file:
- .env.production
depends_on:
db:
condition: service_healthy
deploy:
resources:
limits:
memory: 512M
cpus: "0.5"
read_only: true
tmpfs:
- /tmp
security_opt:
- no-new-privileges:true
Compose Best Practices
| Practice | Why |
|---|
Use depends_on with condition: service_healthy | Prevents app starting before dependencies are ready |
| Set resource limits | Prevents one container from consuming all resources |
| Use named volumes for data | Anonymous volumes are hard to manage |
Use restart: unless-stopped in production | Auto-restart on failure, but not after manual stop |
| Separate dev and prod compose files | Different targets, volumes, and security settings |
Use read_only: true where possible | Prevents runtime filesystem modifications |
.dockerignore
Always include a .dockerignore to keep the build context small and prevent leaking sensitive files.
# Version control
.git
.gitignore
# Dependencies (installed in container)
node_modules
__pycache__
*.pyc
venv/
# Environment and secrets
.env
.env.*
*.pem
*.key
credentials.json
# IDE and editor files
.vscode/
.idea/
*.swp
*.swo
# Build output
dist/
build/
coverage/
*.log
# Docker files (no need to copy into context)
Dockerfile
docker-compose*.yml
compose*.yaml
.dockerignore
# Documentation
*.md
LICENSE
docs/
# Tests (unless needed for build)
tests/
test/
__tests__/
*.test.*
*.spec.*
Anti-Patterns
| Anti-Pattern | Problem | Fix |
|---|
| Running as root | Container compromise = host compromise | Add non-root user, USER appuser |
Using latest tag | Non-reproducible builds | Pin versions: node:20.11-alpine |
| Secrets in ENV/ARG | Visible in image metadata and history | Use runtime env vars or Docker secrets |
| Single-stage builds | Large images with build tools in production | Use multi-stage builds |
No .dockerignore | Large context, potential secret leaks | Always include .dockerignore |
COPY . . before npm install | Cache busted on every code change | Copy package files first, install, then copy code |
| Installing dev dependencies in production | Larger image, larger attack surface | Use npm ci --omit=dev or npm prune --production |
| No health check | Orchestrator cannot detect unhealthy containers | Add HEALTHCHECK instruction |
| Storing data in containers | Data lost when container is removed | Use volumes for persistent data |
| Ignoring image size | Slow pulls, more storage, larger attack surface | Use alpine/distroless, multi-stage, .dockerignore |
apt-get install without cleanup | Cached package lists bloat the layer | apt-get update && apt-get install -y ... && rm -rf /var/lib/apt/lists/* |
Using ADD instead of COPY | ADD has magic behavior (auto-extract, URL fetch) | Use COPY unless you specifically need ADD features |
Production Readiness Checklist
Before deploying a containerized application:
