docker-conventions

Docker Conventions

Best practices for Dockerfiles and container configurations. Focus areas: image size, build cache efficiency, security, and production readiness.

---

Base images

• Use official images with a pinned version tag: python:3.12-slim, node:22-alpine, golang:1.24-alpine.
• Prefer slim (Debian-based, small) or alpine (even smaller, musl libc) variants. Avoid latest — it changes without notice.
• For production, prefer distroless or scratch (Go static binaries) to minimise the attack surface.

# Good: specific version, minimal base
FROM python:3.12-slim

# Bad: unpinned, full Debian base
FROM python:latest

---

Multi-stage builds

Use multi-stage builds to keep the production image small — the build tools (compilers, test runners, dev dependencies) stay in the build stage and never reach the final image.

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

# Stage 2: production
FROM node:22-alpine AS production
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
USER node
CMD ["node", "dist/index.js"]

---

Layer caching

Docker caches layers until a layer (or one of its inputs) changes. Copy dependency files before source code so the dependency install step is cached across code-only changes.

# Good: dependency install cached when only code changes
COPY package*.json ./
RUN npm ci
COPY . .         # ← only invalidates layers from here down

# Bad: copies all source first — dependency install re-runs on every code change
COPY . .
RUN npm install

---

Security

Never embed secrets in a Dockerfile or in a layer. Secrets baked into a layer remain accessible in the image history even if deleted in a later layer.

# WRONG: secret in a layer (visible via `docker history`)
RUN echo "API_KEY=abc123" > /app/.env

# RIGHT: pass secrets at runtime via environment variable or a secret mount
# docker run -e API_KEY=$API_KEY ...
# or use BuildKit secrets for build-time:
RUN --mount=type=secret,id=api_key cat /run/secrets/api_key > /tmp/key