dockerfile-best-practices

name	dockerfile-best-practices
description	Guide for writing production-ready Dockerfiles with multi-stage builds, layer caching, security hardening, and optimized image sizes. Use when the user creates a Dockerfile, asks about Docker image optimization, mentions container security, or needs help with build performance. Trigger whenever Docker or container packaging is discussed.

Dockerfile Best Practices

Write secure, efficient, and maintainable Dockerfiles that produce minimal production images with proper caching, non-root users, and health checks.

When to Use

• User creates or modifies a Dockerfile
• User asks about reducing Docker image size
• User mentions container security or hardening
• User has slow Docker builds or cache invalidation issues
• User asks about COPY vs ADD or layer ordering

Core Patterns

Multi-Stage Builds

Separate build dependencies from runtime to minimize final image size.

# Stage 1: Build
FROM node:20-alpine AS builder
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --ignore-scripts
COPY src/ src/
COPY tsconfig.json ./
RUN npm run build

# Stage 2: 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=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
COPY --from=builder --chown=appuser:appgroup /app/package.json ./
USER appuser
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "dist/index.js"]

Layer Caching Optimization

Order instructions from least to most frequently changed. Copy dependency manifests before source code so dependency installs are cached across builds.

FROM python:3.12-slim

WORKDIR /app

# System deps change rarely -- cache this layer
RUN apt-get update && \
    apt-get install -y --no-install-recommends libpq-dev && \
    rm -rf /var/lib/apt/lists/*

# Dependencies change occasionally -- cache this layer
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# Source code changes frequently -- last layer
COPY . .

CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0"]

Non-Root User

Never run containers as root in production. Create a dedicated user with minimal permissions.

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /server ./cmd/server

FROM scratch
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --from=builder /server /server
USER 65534:65534
ENTRYPOINT ["/server"]

.dockerignore

Always include a .dockerignore to prevent sending unnecessary files to the build context.

.git
.github
node_modules
dist
*.md
.env*
.vscode
.idea
docker-compose*.yml
Dockerfile*
coverage
__pycache__
*.pyc
.pytest_cache

Health Checks

Define health checks in the Dockerfile so orchestrators can monitor container health.

# HTTP health check
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD curl -f http://localhost:8080/healthz || exit 1

# TCP health check (when curl is unavailable)
HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD nc -z localhost 8080 || exit 1

Anti-Patterns

• Using latest tag: Always pin base image versions (node:20.11-alpine, not node:latest). Unpinned tags cause non-reproducible builds.
• Running as root: Never omit the USER instruction. Root in a container is root on the host if the container escapes.
• Using ADD instead of COPY: ADD auto-extracts archives and fetches URLs, which is unexpected. Use COPY for local files; use curl or wget explicitly for remote files.
• Installing dev dependencies in production: Use npm ci --omit=dev or pip install --no-dev in the final stage.
• Single-stage builds: Shipping compilers, build tools, and source code in production images wastes space and expands the attack surface.
• Not cleaning up apt/apk cache: Always add rm -rf /var/lib/apt/lists/* after apt-get install or use --no-cache with apk add.

Quick Reference

Practice	Do	Don't
Base image	node:20-alpine	node:latest
Copy files	COPY . .	ADD . .
User	USER 1001	(run as root)
Install deps	RUN npm ci	RUN npm install
Layer order	deps before source	source before deps
Secrets	--mount=type=secret	COPY .env .
Health	HEALTHCHECK CMD ...	(no health check)
Cache	rm -rf /var/lib/apt/lists/*	(leave cache)