Session 02 · 2h

Building images

From a Dockerfile nobody should ship to Pinboard's real one: 13 MB, non-root, reproducible, signed for what it contains.

Dockerfile Layers & cache Multi-stage & base images Publish & supply chain Lab 02

Session 02

What we'll cover today

1 · The Dockerfile

The build context, .dockerignore, and every instruction you need — FROM through HEALTHCHECK — on a first, honest, terrible Dockerfile.

2 · Layers & the cache

How BuildKit turns instructions into layers, what invalidates the cache, and why instruction order decides whether a rebuild takes 2 s or 2 min.

3 · Small, safe, published

Multi-stage builds, the base-image ladder down to distroless, non-root users, then tagging, multi-platform, SBOM and docker scout.

4 · Lab 02

Write Pinboard's multi-stage Dockerfile yourself, build 1.0 and 1.1, build the web image, and compare the sizes.

Recap session 01 in one sentence: we ran other people's images, today we make our own. Tell them the deck follows one file — src/pinboard-api/Dockerfile — from a naive version to the real one, and that Lab 02 is them typing that file with the blanks filled in.

The Dockerfile

A recipe read top to bottom by a builder — where every line you write becomes something a future colleague has to download.

The flow

What `docker build` actually does

Context

The folder is sent to the builder

→

BuildKit

Parses the Dockerfile into a graph of steps

→

Layers

Runs only the steps not already cached

→

Image

Manifest + config + layers, tagged locally

BuildKit is the default builder in Docker Engine 28 — parallel steps, better caching, cache mounts, secrets
docker buildx build is the same engine with the full flag set; docker build is the friendly front door
The output is a local image; nothing leaves your machine until you push

Point out the numbered #N lines in modern build output and how they map to graph nodes rather than to Dockerfile lines in order — that is BuildKit running independent work in parallel. Mention the first line of our Dockerfile, # syntax=docker/dockerfile:1, which pins the frontend and unlocks newer features regardless of engine version.

Inputs

The build context and `.dockerignore`

The last argument to docker build is a folder, and all of it is uploaded to the builder
COPY can only read from inside that folder — never from ../
.dockerignore keeps junk out: faster builds, smaller images, no leaked secrets
It also protects the cache — a changed .git should not rebuild your app

$ docker build -t pinboard-api:1.0 ./pinboard-api
#1 [internal] load build context
#1 transferring context: 48.2kB done

# pinboard-api/.dockerignore
.git
.gitignore
*.md
.env
Dockerfile
dist/
**/testdata/

The tell-tale sign of a missing .dockerignore is a context transfer of hundreds of megabytes; show that number in the demo. Warn that COPY . . without an ignore file happily bakes .env and private keys into a layer that anyone who pulls the image can extract.

Anatomy

The instructions you actually need

Instruction	What it does	In Pinboard
`FROM`	Starts a stage from a base image	`golang:1.25-alpine AS build`
`WORKDIR`	Sets (and creates) the current directory	`/src`
`COPY`	Copies from context or another stage	`go.mod go.sum ./`
`RUN`	Executes a command, commits a layer	`go mod download`
`ARG` / `ENV`	Build-time variable / runtime variable	`ARG APP_VERSION`, `ENV PORT`
`USER`	Which UID the process runs as	`65532:65532`
`ENTRYPOINT` / `CMD`	The process / its default arguments	`["/pinboard-api"]`
`HEALTHCHECK`	How the engine tests liveness	`curl -f /healthz` (web image)

LABEL adds OCI metadata, EXPOSE documents a port. Prefer COPY over ADD: ADD also fetches URLs and auto-extracts archives, which surprises people.

Do not read the table aloud — call out the three that cause the most trouble: ARG is gone at runtime while ENV ships inside the image, EXPOSE publishes nothing on its own, and ENTRYPOINT versus CMD decides whether arguments replace the program or extend it. Promise the exec-versus-shell form detail for session 03, where signals make it matter.

Start here

A first Dockerfile — and everything wrong with it

FROM golang:1.25-alpine
WORKDIR /src
COPY . .
ENV CGO_ENABLED=0
RUN go build -o /pinboard-api .
EXPOSE 8080
CMD ["/pinboard-api"]

It works. It also produces a 412 MB image containing the Go compiler, your source code and a package manager — running as root.

COPY . . before the build means any file change re-downloads every dependency
No version metadata, no USER, no .dockerignore, nothing pinned

Layers and the cache

Instruction order is not style. It is the difference between a two-second rebuild and a two-minute one, fifty times a day.

Mechanics

Every instruction is a cached step

Instructions that change the filesystem produce a layer; the rest only change config
Layers are content-addressed, so identical layers are stored and pulled once
BuildKit reuses a step when its cache key matches — and prints CACHED
docker history tells you which line cost you which megabytes

$ docker history pinboard-api:1.0
IMAGE      CREATED BY                    SIZE
<missing>  ENTRYPOINT ["/pinboard-api"]     0B
<missing>  USER 65532:65532                 0B
<missing>  COPY /out/pinboard-api / # bui  9.6MB
<missing>  /bin/sh -c #(nop) LABEL org.op   0B
<missing>  distroless base                 1.9MB

The rule that matters

What invalidates the cache

Steps are checked top to bottom; the first miss rebuilds everything after it
COPY/ADD: the key is a checksum of the copied files — content, mode, path
RUN: the key is the command string, not its result — so apt-get update alone can serve week-old package lists
Changing an ARG or ENV a stage uses invalidates from that point
A new base image digest invalidates the whole stage

Always combine apt-get update and apt-get install in one RUN, or you will install yesterday's packages forever.

Put the rarely changing things first and the constantly changing things — your source code — last.

Add that you can opt out of the cache deliberately with --no-cache and --pull. The RUN rule is the counter-intuitive one: BuildKit does not look at what the command produced, only at the text you wrote. Ask the room where source code belongs in a Dockerfile before revealing the answer; the "last" instinct is usually right but rarely applied.

In practice

Ordering Pinboard's build stage

# 1. dependencies change rarely — cache them on their own layer
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download

# 2. the source changes constantly — copy it last
COPY . .
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 go build -o /out/pinboard-api .

Editing a .go file now rebuilds only the last step — dependencies stay CACHED
--mount=type=cache keeps the module and compiler caches outside the image, across builds

Type: docker build -t pinboard-api:naive -f Dockerfile.naive ./pinboard-api, then docker image ls pinboard-api and docker history pinboard-api:naive. Edit the banner string in main.go, rebuild, and point at the missing CACHED markers. Swap to the ordered version, rebuild twice, and show the second run finishing in a couple of seconds with every step CACHED.

Small and safe images

412 MB to 13 MB with one idea: build in one image, ship from another.

The big idea

Multi-stage builds

Several FROMs in one file; each starts a fresh stage
COPY --from=build takes only the artefact across
The toolchain, the source and the module cache never reach the final image

# syntax=docker/dockerfile:1
FROM golang:1.25-alpine AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
ARG APP_VERSION=dev
RUN CGO_ENABLED=0 go build -trimpath -o /out/pinboard-api \
  -ldflags="-X main.defaultVersion=${APP_VERSION}" .
FROM gcr.io/distroless/static-debian12:nonroot AS runtime
COPY --from=build /out/pinboard-api /pinboard-api
EXPOSE 8080
USER 65532:65532
ENTRYPOINT ["/pinboard-api"]

This is the file students write in Lab 02, trimmed of its LABEL block and cache mounts. Walk the two stages and stress the single line that matters — COPY --from=build. Mention --build-arg APP_VERSION=1.1, which is how the same source becomes the 1.1 image we roll out in session 06.

Stage control

Building part of the file: `--target`

# stop at the build stage — a shell, the compiler, the source
docker build --target build -t pinboard-api:builder ./pinboard-api
docker run --rm -it pinboard-api:builder sh

# the real thing
docker build -t pinboard-api:1.0 --build-arg APP_VERSION=1.0 ./pinboard-api

Handy for a test or lint stage that CI builds and production never ships
BuildKit builds independent stages in parallel and skips stages the target does not need
A debug image built from the same stage is far better than adding a shell to production

Give the CI pattern: one Dockerfile with build, test and runtime stages; the pipeline runs --target test then builds the runtime image from the same cache. Mention that docker debug and, later, kubectl debug solve the "no shell in distroless" problem without weakening the image.

Choosing a base

The base-image ladder

Base	Size	Contains	Choose when
`golang:1.25` / `debian:12`	~350–800 MB	Full distro + toolchain	Build stages only
`debian:12-slim`	~75 MB	apt, shell, glibc	You need apt packages at runtime
`alpine:3.22`	~8 MB	busybox, apk, musl	Small and you want a shell
`distroless/static`	~2 MB	CA certs, tzdata, nonroot user	Static binaries — Pinboard's choice
`scratch`	0 B	Nothing at all	You will add certs and a user yourself

Alpine uses musl, not glibc — a real source of surprises with DNS resolution and pre-compiled binaries. Test, don't assume.

Explain that distroless has no shell, no package manager and no busybox, so docker exec ... sh simply fails — that is the point, and the debug story from the previous slide is the answer. Say that pinning a base by digest belongs in this conversation too: alpine:3.22 today is not alpine:3.22 next month.

Least privilege

Don't run as root

Root in a container is root on the host kernel unless user namespaces are on
Distroless :nonroot ships UID 65532; alpine images get an explicit USER
Kubernetes can refuse root images outright with runAsNonRoot: true (session 09)
Non-root cannot bind ports below 1024 — that is why Pinboard listens on 8080, not 80

$ docker run --rm pinboard-api:1.0 id
uid=65532(nonroot) gid=65532(nonroot)

$ docker run --rm nginx:1.28-alpine id
uid=0(root) gid=0(root)

Set USER as the last instruction, after anything that needs to write during the build.

Explain the port rule with the Pinboard web image: it is nginx on 8080 with USER 101:101, exactly because a non-root process cannot take port 80. Note that a read-only root filesystem and dropped capabilities are the next steps, and that we apply both in the Kubernetes security slides.

The payoff

Same binary, one twentieth the size

412 MB

Naive

golang:1.25-alpine with the source, the compiler and the module cache still inside. Runs as root.

23 MB

Alpine runtime

Multi-stage onto alpine:3.22. Has a shell — convenient, and an attack surface.

13 MB

Distroless

Binary + certs + nonroot user. Nothing to exec into, nothing to exploit.

Multiply by every node that pulls it, every rollout, every CI run. Small images make session 06's rolling updates feel instant.

Type: docker build -t pinboard-api:1.0 --build-arg APP_VERSION=1.0 ./pinboard-api, then docker image ls pinboard-api. Try docker run --rm -it pinboard-api:1.0 sh and let it fail, then docker build --target build -t pinboard-api:builder . and get a shell there instead. Finish with docker run --rm -p 8080:8080 pinboard-api:1.0 and curl -s localhost:8080/api/info to show the version we injected via the build arg.

Publish and prove

Getting the image to a registry — and being able to say, later, exactly what is in it and where it came from.

Scaffolding

`docker init` — don't start from a blank file

$ cd src/pinboard-api && docker init

? What application platform does your project use?  Go
? What version of Go do you want to use?           1.24
? What port does your server listen on?            8080

Created: .dockerignore, Dockerfile, compose.yaml, README.Docker.md

Generates a sane multi-stage Dockerfile, a .dockerignore and a Compose file for Go, Node, Python, Rust, PHP and ASP.NET
Treat it as a draft: check the base image, the USER, the pinning and the health check before committing

Ship it

Tag and push

docker login ghcr.io                      # credentials go to ~/.docker/config.json
docker tag pinboard-api:1.0 ghcr.io/zonoth/pinboard-api:1.0
docker push ghcr.io/zonoth/pinboard-api:1.0

# or build straight to the registry
docker buildx build --push -t ghcr.io/zonoth/pinboard-api:1.0 ./pinboard-api

A tag is just a pointer — the same image can carry 1.0, 1 and a commit SHA at once
push uploads only the layers the registry is missing
OCI labels (org.opencontainers.image.version, .source, .revision) travel inside the image — Pinboard sets them in its LABEL block

Explain the CI convention: an immutable tag per build, usually the git SHA, plus moving tags like 1.0 or stable for humans. Point out that .source is what makes a registry link back to the repository, and that annotations are the equivalent metadata on the manifest rather than the config.

Architectures

Multi-platform images

docker buildx create --name multi --use
docker buildx build --platform linux/amd64,linux/arm64 \
  -t ghcr.io/zonoth/pinboard-api:1.0 --push ./pinboard-api
docker buildx imagetools inspect ghcr.io/zonoth/pinboard-api:1.0

One tag becomes an image index listing a manifest per architecture; the daemon picks the right one automatically
Go cross-compiles for free — use $TARGETPLATFORM in the build stage instead of QEMU emulation, which is slow
Multi-platform results cannot sit in the classic local image store: use --push, or --load a single platform

This matters in every mixed room: Apple silicon laptops build arm64 by default, while most clusters are amd64, and the resulting exec format error is a rite of passage. Mention that imagetools inspect is how you check what a published tag really contains.

Supply chain

SBOM, provenance, and a scan

docker buildx build --sbom=true --provenance=mode=max \
  -t ghcr.io/zonoth/pinboard-api:1.0 --push ./pinboard-api

docker scout quickview pinboard-api:1.0
docker scout cves pinboard-api:1.0 --only-severity critical,high

SBOM — the bill of materials: every package inside the image, in SPDX form
Provenance — how it was built: source, builder, arguments (SLSA-style attestation)
Both attach to the image index as attestations and travel with the image
docker scout compares those contents against advisory data and suggests a better base

Before you commit

Dockerfile best-practice checklist

Size & base

Multi-stage build · smallest base that works · pin the tag (ideally the digest) · no compilers or package managers in the runtime stage.

Cache & context

Dependencies before source · one RUN for update+install · a real .dockerignore · cache mounts instead of copied caches.

Security

USER non-root · no secrets in layers (use --mount=type=secret) · only the ports you need · a scan in CI.

Metadata & runtime

OCI LABELs · version via ARG · ENTRYPOINT in exec form · HEALTHCHECK · config from env, never baked in.

Point out that every one of these is satisfied by src/pinboard-api/Dockerfile — read it as the worked example. Tell students to photograph this slide; it is the review checklist for Lab 02 and for the capstone. Call out the secrets line especially: a build argument is visible in docker history, so credentials must go through --mount=type=secret and never through ARG.

Type: docker buildx build --platform linux/amd64,linux/arm64 --sbom=true --provenance=mode=max -t pinboard-api:1.0 --push . against a local registry if you have no network, then docker buildx imagetools inspect to show the per-architecture manifests and the attestation entries. Finish with docker scout quickview pinboard-api:naive versus pinboard-api:1.0 — the difference in the CVE counts sells the whole session.

Set the storyline: these are the exact two image versions we roll out against each other in session 06, so the 1.1 build is not busywork. The solution Dockerfile is in labs/solutions/lab02/ — tell them to try before peeking. The optional push step needs a Docker Hub account and can be skipped entirely.

Session 02

Key takeaways

Order for the cache

Rarely-changing steps first, source last. The first cache miss rebuilds everything below it.

Build here, ship from there

Multi-stage plus a minimal base turned 412 MB into 13 MB with the same binary.

Non-root, pinned, described

USER, a pinned base, OCI labels, an SBOM and a scan — the 2026 minimum.

Next up

Session 03 — running containers well: configuration, signals and PID 1, volumes and networking.

Check understanding with two questions: "you changed one line of Go — which layers rebuild?" and "why can't you exec a shell in our production image?". Then tease session 03: the images are built, but the notes still vanish when the database container is removed.

Questions?

Up next — Session 03: Running containers well. Configuration, storage and networking, with Pinboard wired together by hand.

Building images

What we'll cover today

1 · The Dockerfile

2 · Layers & the cache

3 · Small, safe, published

4 · Lab 02

The Dockerfile

What docker build actually does

Context

BuildKit

Layers

Image

The build context and .dockerignore

The instructions you actually need

A first Dockerfile — and everything wrong with it

Layers and the cache

Every instruction is a cached step

What invalidates the cache

Ordering Pinboard's build stage

Watch the cache work — and break

Small and safe images

Multi-stage builds

Building part of the file: --target

The base-image ladder

Don't run as root

Same binary, one twentieth the size

Naive

Alpine runtime

Distroless

Naive to multi-stage, side by side

Publish and prove

docker init — don't start from a blank file

Tag and push

Multi-platform images

SBOM, provenance, and a scan

Dockerfile best-practice checklist

Size & base

Cache & context

Security

Metadata & runtime

Attest and scan the image we just built

Build the Pinboard images

Key takeaways

Order for the cache

Build here, ship from there

Non-root, pinned, described

Next up

Questions?

What `docker build` actually does

The build context and `.dockerignore`

Building part of the file: `--target`

`docker init` — don't start from a blank file