Cheat sheet

Dockerfile Best Practices

Layering, caching, and security guidance for production images.

Back to cheats

Layering strategy

Order layers from least to most frequently changing.

Install dependencies before copying full app source.

Combine commands with && to reduce layers.

Remove build-only artifacts in the same layer.

Caching wins

Copy only dependency manifests first (package.json, requirements.txt).

Use a .dockerignore to exclude node_modules, build outputs, and secrets.

Pin base image versions for stable cache hits.

Prefer multi-stage builds to keep runtime layers small.

Security practices

Use minimal base images (distroless, alpine when safe).

Create a non-root user and switch with USER.

Avoid baking secrets into images; use runtime env or secrets.

Scan images for vulnerabilities as part of CI.

Performance and size

Leverage multi-stage builds to exclude dev deps.

Remove package manager caches (apt, apk, npm cache).

Prefer COPY --link (BuildKit) for large trees.

Limit layers with large binaries or logs.

Node.js multi-stage

Separate deps, build output, and runtime layers.

# syntax=docker/dockerfile:1
FROM node:20-alpine AS deps
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci

FROM node:20-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN npm run build

FROM node:20-alpine AS runtime
WORKDIR /app
ENV NODE_ENV=production
RUN addgroup -S app && adduser -S app -G app
COPY --from=build /app/dist ./dist
COPY --from=build /app/package.json ./package.json
USER app
EXPOSE 3000
CMD ["node", "dist/server.js"]

Python slim image

Slim base with build deps only in the build stage.

# syntax=docker/dockerfile:1
FROM python:3.12-slim AS base
ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1
WORKDIR /app

FROM base AS build
RUN apt-get update && apt-get install -y --no-install-recommends build-essential && rm -rf /var/lib/apt/lists/*
COPY pyproject.toml poetry.lock ./
RUN pip install --no-cache-dir poetry && poetry export -f requirements.txt --output requirements.txt
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

FROM base AS runtime
RUN adduser --disabled-password --gecos "" app
COPY --from=build /usr/local /usr/local
COPY --from=build /app /app
USER app
EXPOSE 8000
CMD ["python", "app.py"]

Static site + Nginx

Build assets once, serve from a minimal runtime image.

# syntax=docker/dockerfile:1
FROM node:20-alpine AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:1.27-alpine AS runtime
COPY --from=build /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

About the Dockerfile Best Practices cheat sheet

Almost every Dockerfile problem is one of two things: a layer order that defeats the build cache, or an image that ships far more than it needs to run. Both come from writing the file in the order you happen to think of the steps rather than in the order the cache wants.

The cache rule is simple and rarely followed. Each instruction produces a layer, and changing one invalidates everything after it. Copying your whole source tree before installing dependencies means every source edit reinstalls every dependency. Copy the manifest, install, then copy the source — that single reordering is usually the largest build-time win available.

The size rule is multi-stage builds. Compilers, headers, test fixtures and package caches belong in a build stage; the final stage should contain the artefact and its runtime dependencies. This is a security control as much as a size one, because a toolchain that is not in the image cannot be used by anyone who gets into it.

Frequently asked questions

Why does my build reinstall dependencies on every code change?

Because the source is copied before the install step, so editing any file invalidates the layer the install sits on. Copy only the dependency manifest first, run the install, then copy the rest of the source. The install layer is then reused until the manifest itself changes, which is usually rarely.

Should I use alpine for smaller images?

Sometimes, and it is not free. Alpine uses musl instead of glibc, which can cause subtle runtime differences and notably slower DNS resolution in some workloads, and Python wheels often need compiling rather than installing prebuilt. Distroless or slim variants frequently give most of the size benefit without the libc change. Measure both rather than assuming alpine is the smaller answer.

How do I keep secrets out of the image?

Never pass them as build arguments — build args are visible in image history to anyone who pulls it, and removing a file in a later layer does not remove it from earlier ones. Use BuildKit secret mounts, which make the value available during a single instruction without persisting it into any layer. For runtime configuration, inject at run time rather than baking it in.

Why should containers not run as root?

A process running as root inside the container is root in the namespace, so a container escape or a mounted host path starts from the strongest position rather than the weakest. Create a user in the image and switch to it before the entrypoint. Some platforms enforce this — OpenShift assigns arbitrary non-root UIDs, so images that assume root simply fail to start.

What is the difference between COPY and ADD?

COPY does exactly what it says. ADD additionally unpacks local archives and can fetch remote URLs, both of which are surprising behaviours to inherit accidentally. Default to COPY, and use ADD only when you specifically want archive extraction. For remote files, fetching explicitly makes the download visible and lets you verify a checksum.

Need this managed for you, not just automated?

We're also a hands-on DevOps consultancy — Kubernetes, CI/CD, and cloud infrastructure.

Explore Our Services