Chapter Four

Dockerfiles

The text file that turns the layer stack into code. How docker build packs a directory and ships it to the daemon, why instruction order is the difference between a 90-second rebuild and a 2-second one, and the instructions that decide what runs, who it runs as, and what it declares about itself — RUN, COPY, ADD, CMD, ENTRYPOINT, ARG, ENV, and the metadata that sets a container's posture.

7 topics

A Dockerfile is a recipe the daemon reads top to bottom, each instruction committing a new layer on top of the last. That makes the Dockerfile the layer stack from Chapter 2 written out as code — which is also why authoring one well is mostly about understanding what each instruction puts in a layer and when the build cache can skip it.

This chapter writes Driftwood's first Dockerfile — a naive single-stage build — and then fixes it. You will see why docker build ships a whole directory to the daemon before any instruction runs, why ordering the dependency install above the source copy turns a 90-second rebuild into a 2-second one, and how RUN, COPY, ADD, CMD, ENTRYPOINT, ARG, and ENV each behave — including the exec-vs-shell choice that decides whether your process is PID 1 and answers docker stop. The multi-stage rebuild that slims this image comes in Chapter 5; here you learn the instructions cold.

Topics in This Chapter

The Dockerfile Model and Build Context

A Dockerfile is a recipe executed top to bottom, each instruction a layer. But the build context — the directory tarred up and shipped to the daemon first — decides how fast and how fat the build is, and what COPY can reach.

Layer Caching and Instruction Order

The chapter spine: the cache reuses each layer until the first changed instruction, then rebuilds everything below it. Copy the dependency manifest before the source code and a 90-second rebuild becomes a 2-second one.

RUN — Shell Form vs Exec Form

RUN executes a command at build time and commits a layer. Shell form wraps it in /bin/sh -c; exec form runs the binary directly. The same fork returns in CMD and ENTRYPOINT, where it decides PID 1 and signals.

InstructionBuild

Both move files from the context into the image, and for plain copying they are identical. ADD also auto-extracts local tarballs and fetches URLs — two footguns. Use COPY for everything; reserve ADD for the one case it earns.

InstructionFiles

CMD vs ENTRYPOINT

The most-confused pair in the Dockerfile. ENTRYPOINT is the fixed executable; CMD is the default arguments docker run can override. Exec form makes the process PID 1 so docker stop reaches it cleanly.

InstructionRuntime

Both set values; the difference is when they exist. ARG is build-time only and vanishes from the container — but lingers in docker history. ENV persists into the running container. Neither is a safe place for secrets.

InstructionConfig

WORKDIR, USER, EXPOSE, LABEL, and Metadata

The instructions that set a container's posture: where it runs, who it runs as, what it advertises, and what it declares. USER root by default is a real risk, and EXPOSE does far less than people assume.

InstructionPosture