Writing Dockerfiles: caching, multi-stage builds and small images

Why a Dockerfile?

You could start a container, install things by hand and save it, but nobody could repeat or review those steps. A Dockerfile is a plain text file in your repository that lists every step to build the image. It is reviewed in pull requests and rebuilt the same way by CI every time.

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
RUN useradd --create-home appuser
USER appuser
EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app:app"]

The main instructions

CMD and ENTRYPOINT, and the exec form

Write CMD and ENTRYPOINT in exec form, a JSON list such as CMD ["node", "server.js"]. The shell form, CMD node server.js, runs your app through /bin/sh -c, so the shell becomes the main process and your app may not receive the stop signal. Then docker stop waits 10 seconds and kills it, and your app never closes connections cleanly.

ENTRYPOINT ["python", "report.py"]
CMD ["--month", "current"]
# docker run reports            → python report.py --month current
# docker run reports --month 09 → python report.py --month 09

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -f http://localhost:8000/health || exit 1

Layer caching: order matters

Docker caches the result of each instruction. On the next build, it reuses cached layers until it reaches the first instruction whose input changed; that step and every step after it run again. Your code changes many times a day, but your dependency list changes rarely. So copy only the dependency files first, install, and then copy the rest.

# Slow: any code change re-runs npm ci
COPY . .
RUN npm ci

# Fast: npm ci re-runs only when package files change
COPY package.json package-lock.json ./
RUN npm ci
COPY . .

.dockerignore

The build context is everything in the folder you pass to docker build. A .dockerignore file lists what to leave out, using patterns like .gitignore. This keeps builds fast, keeps the cache stable and, most importantly, keeps secrets out of the image.

.git
node_modules
__pycache__
*.log
.env
dist

Multi-stage builds

Building needs compilers, dev dependencies and source code; running needs only the result. A multi-stage build uses several FROM lines. Early stages build; the final stage copies just what is needed with COPY --from. Everything else is left behind, so the final image is smaller and has fewer tools an attacker could use.

FROM golang:1.24 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/server ./cmd/server

FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/server /server
EXPOSE 8080
ENTRYPOINT ["/server"]

FROM node:24-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:24-slim
ENV NODE_ENV=production
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
USER node
CMD ["node", "dist/server.js"]

Keeping images small

• Start from a small base: -slim variants (Debian with fewer packages), -alpine (very small, but uses musl instead of glibc, which can break some compiled Python packages), or distroless images that contain only your app and its runtime, with no shell or package manager.
• Install only what you need: apt-get install --no-install-recommends, and clean up in the SAME RUN: rm -rf /var/lib/apt/lists/*. Files deleted in a later layer still take space in the earlier one.
• Use pip install --no-cache-dir and npm ci --omit=dev in the final image.

Common mistakes

• FROM python with no tag (that is :latest): your build changes when the base changes. Pin python:3.12-slim.
• apt-get update in one RUN and apt-get install in a later RUN: the cached update can be stale. Combine them in one RUN.
• No USER line: the app runs as root inside the container.