4.1.1.1 Dockerfile Build Steps
A focused guide to Dockerfile Build Steps, connecting core concepts with practical Docker and container operations.
Dockerfile build steps are the individual instructions that, executed in sequence, transform a base image into the final image — each step either modifying the filesystem or adjusting metadata that will carry forward into the resulting image.
The Lifecycle of a Single Build Step
For each filesystem-modifying instruction, the build process starts a temporary container from the current state, executes the instruction inside it, captures the resulting change as a new layer, and discards the temporary container, leaving only the new layer behind.
FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y curl
Building this involves one such step: starting from the base image, running the install command inside a temporary container, and committing the resulting filesystem change as a new layer.
docker build -t myapp .
Watching Build Steps Execute
The build process reports its progress step by step, which is useful both for understanding how long each part of a build takes and for diagnosing exactly where a build failure occurred.
docker build --progress=plain -t myapp .
This produces detailed, step-by-step output showing each instruction as it executes, rather than a more condensed default view.
Steps That Affect Metadata Without Filesystem Changes
Not every instruction produces a new filesystem layer — instructions like ENV, EXPOSE, and CMD only modify the image's metadata, which is recorded without the overhead of creating and discarding a temporary container for filesystem changes.
ENV NODE_ENV=production
EXPOSE 3000
CMD ["node", "server.js"]
Why Understanding Build Steps Individually Matters
Recognizing that each instruction is its own discrete, independently cached, independently executed step clarifies both how the build cache works and how to interpret build failures — a failure reported at a specific step points directly at the instruction responsible, rather than leaving the entire build process as an opaque, monolithic operation.
docker build -t myapp . 2>&1 | grep -A5 "Step"