The Dockerfile Model and Build Context

A Dockerfile is a recipe: a text file of instructions the daemon executes top to bottom, each one producing a new image layer on top of the last. But docker build does not read that file in isolation — it first packs up a directory, the build context, and ships the whole thing to the daemon, and only then runs the instructions.

The size of that context, and what COPY can reach inside it, decide how fast and how fat the build is. A build that uploads a 4 GB directory before it executes a single line is slow for a reason that has nothing to do with the instructions — and a COPY . . that sweeps in node_modules and a .git history bakes the junk into the image. The model is two halves: the recipe, and the directory the recipe runs against.

The Recipe, Top to Bottom

A Dockerfile starts FROM a base image and applies instructions — RUN, COPY, ENV, CMD — in the order they appear. Each instruction that changes the filesystem commits a new read-only layer, exactly the layer stack from Chapter 2. So the Dockerfile is that stack written out as code: read it top to bottom and you are reading the layers bottom to top.

FROM python:3.12
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
EXPOSE 8000
CMD ["gunicorn", "--bind", "0.0.0.0:8000", "app:app"]

Six instructions, and every filesystem-changing one — the COPY and the RUN — is a layer. This is the image the chapter starts from and spends the next topic fixing: it works, it serves Driftwood on port 8000, and its instruction order quietly defeats the build cache. Reasoning about each line as "this commits a layer" is how you predict that before it costs you.

The Build Context

docker build . tars up that . directory — the build context — and uploads it to the daemon before any instruction runs. COPY ./app /app can only reach files inside that context, which is why a path that climbs out of it, like COPY ../secrets /etc, fails with a "forbidden path" error rather than reaching up the tree. The context is a sealed box; the build sees nothing outside it.

This is also why the argument to docker build matters as much as the Dockerfile. Build from a directory scoped to the application and the context holds only what the image needs; build from a sprawling monorepo root and the context is the whole tree, whether or not any COPY names those files.

Why the Daemon, Not the CLI, Builds

The client sends the context over the daemon socket and the daemon does the work. A 2 GB context is a 2 GB upload even when the daemon sits on the same machine — there is no shortcut for "local." It is why the build output includes a transferring context step with a byte count (the classic builder phrased this Sending build context to Docker daemon), and why a build against a remote daemon is slow before it has run a single instruction: the context crosses the wire first.

The Context Footgun

Run docker build . in a directory that holds node_modules, a .git history, build output, and a 4 GB dataset, and all of it ships to the daemon every build — tens of seconds of upload before the first instruction even runs. Worse, a COPY . . then bakes that junk straight into the image: the dataset, the git history, and the local virtualenv become layers you push to a registry and pull onto every host.

.dockerignore, Previewed

A .dockerignore file excludes paths from the context the way .gitignore excludes them from a commit. List .git/ and node_modules/ there and they never get uploaded, so the context shrinks and COPY . . can no longer sweep them in. This topic only teases it; Chapter 5 builds Driftwood's real .dockerignore alongside the multi-stage build that makes it matter.