Building Images

In one sentence: A build file is a list of instructions, and the builder executes each one inside a temporary container, snapshotting the filesystem changes as a new layer — so an image is literally its own construction history.

Run, diff, commit, repeat

The builder's core loop is elegantly circular: to build an image, run containers. For each instruction — "copy these files in", "run this install command", "set this env var" — the builder starts a temporary container from the layers built so far, applies the instruction, and captures the result. Filesystem-changing instructions (COPY, RUN) produce a new layer (the upper dir, tarred). Metadata instructions (ENV, CMD, EXPOSE) touch only the config — no layer at all. The inputs are the build file plus a build context: the directory of files the client ships to the daemon, the only files COPY can ever see.

flowchart LR
  BF["build file
(instruction list)"] --> B["builder"]
  CTX["build context
(files sent by client)"] --> B
  B --> TMP["temp container
from layers so far"]
  TMP -- "capture upper dir" --> NL["new layer"]
  NL -- "becomes base for
next instruction" --> TMP
  B --> CFG["image config
(cmd, env — no layers)"]
  NL --> IMG["final image:
layers + config + manifest"]
  CFG --> IMG
    

Three instructions, three snapshots

sequenceDiagram
  participant C as Client
  participant B as Builder (in daemon)
  participant T as Temp container
  C->>B: build (sends build file + context)
  B->>T: start from base image; COPY app/ /app
  T-->>B: diff captured → layer 1
  B->>T: start from base+L1; RUN install deps
  T-->>B: diff captured → layer 2
  B->>B: CMD "serve" → config only, no container needed
  B-->>C: image built: base + L1 + L2 + config
  note over B: each snapshot is a normal layer —
the image is its own build history