Cheat sheet

Dockerfile Best Practices

Layering, caching, and security guidance for production images.

Back to tools

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;"]

# 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"]

# 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"]

# 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;"]