Sign in Get started

DevOps Tutorial · Containers and Kubernetes · Lesson 17 of 25

Writing Good Dockerfiles

Small, fast, secure images: layer caching, multi-stage builds, non-root users, .dockerignore and pinned base images.

Create a free account to save this page, take notes and track your progress. Sign in

A production Dockerfile

# syntax=docker/dockerfile:1
FROM python:3.13-slim AS build
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir --prefix=/install -r requirements.txt

FROM python:3.13-slim
WORKDIR /app
COPY --from=build /install /usr/local
COPY src/ ./src/
RUN useradd --uid 10001 --no-create-home app
USER app
EXPOSE 8080
CMD ["gunicorn", "-b", "0.0.0.0:8080", "src.app:app"]

The rules behind it

  1. Order layers by how often they change. Dependencies first, source code last, so a code change doesn't reinstall every package. Each instruction is a cached layer; a change invalidates it and every layer after it.
  2. Multi-stage builds: compilers and build tools stay in the build stage; the final image only gets the results.
  3. Small base images (-slim, distroless, Alpine where compatible) mean fewer vulnerabilities.
  4. Run as a non-root user (USER).
  5. Exec-form CMD (["gunicorn", ...]) so the app is PID 1 and receives SIGTERM.
  6. Never copy secrets into an image; deleting them in a later layer doesn't remove them from earlier layers. Use BuildKit secret mounts (RUN --mount=type=secret,...).
  7. .dockerignore keeps .git, node_modules, local .env files and test data out of the build context.
  8. Pin the base image to a version, or a digest for full reproducibility, not latest.
Why instruction order matters for cachingTry it yourself
def build(instructions, changed):
    rebuilt, invalid = [], False
    for name, inputs in instructions:
        if invalid or inputs & changed:
            invalid = True
            rebuilt.append(name)
    return rebuilt

good = [("FROM base", set()), ("COPY requirements.txt", {"requirements.txt"}),
        ("RUN pip install", set()), ("COPY src/", {"src/app.py"})]
bad = [("FROM base", set()), ("COPY . .", {"requirements.txt", "src/app.py"}), ("RUN pip install", set())]

print("good order, app.py changed -> rebuild:", build(good, {"src/app.py"}))
print("bad order,  app.py changed -> rebuild:", build(bad, {"src/app.py"}))

Output

good order, app.py changed -> rebuild: ['COPY src/']
bad order,  app.py changed -> rebuild: ['COPY . .', 'RUN pip install']

Test yourself

Why copy requirements.txt and install dependencies before copying the source code?

  1. So code changes don't invalidate the cached dependency layer
  2. Docker requires that order
  3. It makes the image run as non-root
  4. It removes secrets from the image
Show answer

Answer: So code changes don't invalidate the cached dependency layer

A layer is rebuilt when its inputs change, and so is every layer after it.

Was this page helpful?