docker-patterns

Docker Patterns

Dockerfile optimisation, multi-stage builds, image security, and container best practices. Run the linter on every Dockerfile before review; use this prose guidance to explain findings and propose fixes.

Purpose

• Produce small, secure production images using multi-stage builds
• Maximise layer cache hit rate to speed up CI pipelines
• Eliminate common image security vulnerabilities
• Ensure containers are production-ready with health checks

---

Multi-Stage Build Pattern

Split the image into a builder stage (compile / install) and a runtime stage (minimal base). Never ship build tools in production images.

# syntax=docker/dockerfile:1

# Stage 1: Builder
FROM node:20-alpine AS builder
WORKDIR /app

# Copy dependency manifests first (cache layer)
COPY package.json package-lock.json ./
RUN npm ci --frozen-lockfile

# Copy source and build
COPY . .
RUN npm run build

# Stage 2: Runtime (never includes node_modules/devDependencies or build tools)
FROM node:20-alpine AS runtime
WORKDIR /app

# Non-root user
RUN addgroup -S appgroup && adduser -S appuser -G appgroup
USER appuser

# Copy only production artefacts from builder
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules

EXPOSE 3000
ENTRYPOINT ["node", "dist/server.js"]

Why this matters: A typical Node.js image with dev dependencies can reach 800MB+. The runtime-only image is typically under 100MB.

---

Layer Caching Optimisation

Docker caches each instruction. If a layer's checksum changes, all subsequent layers are invalidated.

Optimal ordering (least-to-most-frequently-changing):

# 1. Base image (changes rarely)
FROM python:3.12-slim

# 2. System dependencies (changes rarely)
RUN apt-get update && apt-get install -y --no-install-recommends \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# 3. App dependency manifests (changes when you add/remove packages)
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 4. Source code (changes every commit — LAST)
COPY . .