Skip to content
Hands-on IT IT Drills

Day 0: The Training Ground

Goal: Check Docker with BuildKit, start a local registry and builder, set up the demo application notes and build the naive Dockerfile for the first time. · Duration: approx. 45 min · Prerequisite: none

Briefing

  • Docker runs in a small Linux VM managed by Colima. The docker command on the Mac talks to the daemon in the VM over a socket.
  • Builds use BuildKit, via docker build (builder default) or docker buildx build (a dedicated builder docker-lab for cache export, multi-platform and attestations).
  • A local registry on localhost:5001 replaces Docker Hub, GHCR or Harbor: you push and pull images without an account and without publishing anything.
  • The demo application notes has three services and a deliberately bad Dockerfile that you improve over the next 15 days.
 Mac                                         Colima VM (Linux, arm64)
 ┌──────────────────────────────┐            ┌───────────────────────────────────┐
 │ ~/docker-lab/                │   Socket   │ Docker daemon + BuildKit          │
 │   setup/  env.sh             │ ─────────► │   Builder "default"               │
 │   notes/  api, worker, web   │            │   Container "buildx_buildkit_     │
 │   code/   companion code     │            │     docker-lab0" (builder)        │
 │   tagNN/  your work          │   :5001    │   Container "docker-lab-registry" │
 │ docker, buildx, hadolint ... │ ◄────────► │     registry:3.0.0                │
 └──────────────────────────────┘            └───────────────────────────────────┘

Drill 1: Check the tools

docker version --format 'Client {{.Client.Version}} / Server {{.Server.Version}}'
docker buildx version
docker compose version
colima version | head -1
hadolint --version
trivy --version | head -1
dockle --version
shellcheck --version | sed -n 2p
jq --version
git --version

Expected (abbreviated, may vary by version):

Client 29.9.0 / Server 29.9.0
github.com/docker/buildx v0.38.0 Homebrew
Docker Compose version 5.6.0
colima version 0.10.3
Haskell Dockerfile Linter 2.14.0
Version: 0.75.0
dockle version 0.4.15
version: 0.11.0
jq-1.8.2
git version 2.56.0

If something is missing: brew install colima docker docker-buildx docker-compose hadolint trivy shellcheck jq and brew install goodwithtech/r/dockle (dockle lives in its own tap). On Linux you don’t need Colima; Docker Engine with buildx and Compose is enough; hadolint, trivy and dockle are available there as release binaries with a checksum file, ShellCheck as the package shellcheck. Docker Desktop works as well; it then replaces Colima.

Warning: If docker version reports failed to connect to the docker API for the server, the VM isn’t running or is still starting. Check with colima status, wait until “colima is running” appears, and use docker context ls to see whether the context colima is active (docker context use colima).

Save your progress? Sign up for free

Drill 2: Colima, image store and disk space

colima status
docker info --format 'Arch {{.Architecture}} · CPUs {{.NCPU}} · Storage {{.Driver}}'
df -h ~ | tail -1
docker system df

Expected (abbreviated, may vary by version):

INFO[0000] colima is running using macOS Virtualization.Framework
INFO[0000] arch: aarch64
INFO[0000] runtime: docker
INFO[0000] mountType: virtiofs
Arch aarch64 · CPUs 4 · Storage overlayfs
/dev/disk3s1s1   228Gi    17Gi    11Gi    62%    426k  112M    0%   /
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          4         1         1.9GB     1.4GB (73%)
Containers      1         1         0B        0B
Local Volumes   2         1         210MB     0B
Build Cache     38        0         640MB     640MB

Remember two values:

  • Storage overlayfs means: Docker uses the containerd image store. Then docker can keep multi-platform images and attestations locally (Day 7, Day 10). If it says overlay2, the classic store is running; the book still works, you then push such images directly to the registry instead of loading them locally.
  • Free space: Images, build cache and volumes live in Colima’s VM disk, which in turn takes up space on the Mac. Keep at least 5 GB free and clean up selectively after each day (Drill 9).

Warning: docker system prune -a also removes the images and caches of other projects. In this book you only clean up lab traces, with the three commands from Drill 9.

Save your progress? Sign up for free

Drill 3: Working directory and companion code

You fetch the companion code once from GitHub into ~/docker-lab/code. The setup file and the demo application get their own folders so you can change them without losing the original:

mkdir -p ~/docker-lab/tag00 && cd ~/docker-lab
git clone https://github.com/thomaszachmann/dockerfiles-zum-anfassen.git \
  ~/docker-lab/code
cp -R ~/docker-lab/code/setup ~/docker-lab/setup
cp -R ~/docker-lab/code/notes ~/docker-lab/notes
ls ~/docker-lab ~/docker-lab/setup

Expected:

Cloning into '/Users/du/docker-lab/code'...
/Users/du/docker-lab:
code    notes   setup   tag00

/Users/du/docker-lab/setup:
env.sh

env.sh only sets variables that all drills use:

grep -v '^#' ~/docker-lab/setup/env.sh

Expected:

export LAB="${LAB:-$HOME/docker-lab}"
export REG_NAME="${REG_NAME:-docker-lab-registry}"
export REG_PORT="${REG_PORT:-5001}"   # nicht 5000: AirPlay-Empfänger unter macOS
export REGISTRY="localhost:$REG_PORT"
export BUILDER="${BUILDER:-docker-lab}"
export NOTES="$LAB/notes"

From now on, every day starts with the same line:

source ~/docker-lab/setup/env.sh

Save your progress? Sign up for free

Drill 4: Start the registry and builder

The registry is an ordinary container: registry:3.0.0, reachable only on 127.0.0.1:5001, with a volume for the data. --restart unless-stopped brings it back up automatically after every restart of Colima.

docker run -d --name docker-lab-registry --restart unless-stopped \
  -p 127.0.0.1:5001:5000 -v docker-lab-registry-data:/var/lib/registry \
  registry:3.0.0

Expected (abbreviated, ID differs):

Unable to find image 'registry:3.0.0' locally
…
Status: Downloaded newer image for registry:3.0.0
0b54e1a1002e…

The builder docker-lab runs as its own BuildKit container (driver docker-container). network=host lets it reach the registry at localhost:5001, --bootstrap starts it right away instead of on the first build:

docker buildx create --name docker-lab --driver docker-container \
  --driver-opt network=host --bootstrap
docker ps --filter name=docker-lab --format '{{.Names}}\t{{.Image}}\t{{.Status}}'
docker buildx ls

Expected (abbreviated, may vary by version):

#1 [internal] booting buildkit
…
docker-lab
buildx_buildkit_docker-lab0   moby/buildkit:buildx-stable-1   Up 3 seconds
docker-lab-registry           registry:3.0.0                  Up 5 seconds
NAME/NODE          DRIVER/ENDPOINT                   STATUS    BUILDKIT   PLATFORMS
docker-lab         docker-container
 \_ docker-lab0     \_ unix:///…/docker.sock          running   v0.26.2    linux/arm64
default*           docker
 \_ default         \_ default                        running   v0.26.1    linux/arm64

The asterisk stays on default: without --builder docker-lab, docker build keeps building with the built-in builder, whose images show up in docker image ls right away. You use the builder docker-lab only when a day tells you to.

The registry speaks the OCI Distribution API, so you can query it with curl:

curl -s http://localhost:5001/v2/_catalog

Expected:

{"repositories":[]}

Both commands only create what is missing: if the registry is already running, docker run reports a name conflict; if the builder already exists, buildx create refuses. You can ignore both.

Save your progress? Sign up for free

Drill 5: Check the training ground

You run the same checks whenever something gets stuck later. First the registry, then the builder:

source ~/docker-lab/setup/env.sh
curl -s -o /dev/null -w '%{http_code}\n' "http://$REGISTRY/v2/"
docker buildx inspect "$BUILDER" | grep -E '^(Name|Driver|Status):'

Expected:

200
Name:          docker-lab
Driver:        docker-container
Name:                  docker-lab0
Status:                running

000 instead of 200 means: the registry isn’t running; docker start docker-lab-registry brings it back. If the builder shows inactive or stopped, the next build with --builder docker-lab starts it automatically. Finally, tools, demo application and disk space:

command -v hadolint trivy jq
ls "$NOTES/notes-api/main.go"
df -h ~ | tail -1

Expected (abbreviated, paths and sizes differ):

/opt/homebrew/bin/hadolint
/opt/homebrew/bin/trivy
/opt/homebrew/bin/jq
/Users/du/docker-lab/notes/notes-api/main.go
/dev/disk3s1s1   228Gi    17Gi    11Gi    62%    426k  112M    0%   /

The fourth column shows at least 5 GB.

Save your progress? Sign up for free

Drill 6: Get to know the demo application

cd ~/docker-lab/notes
ls -A . notes-api notes-worker notes-web

Expected:

.:
.env            .env.example    notes-api       notes-web       notes-worker
README.md

notes-api:
Dockerfile.naiv go.mod          go.sum          main.go

notes-worker:
pyproject.toml  src             uv.lock

notes-web:
package-lock.json       package.json    public  server.js       src
Service Language Port Role in the book
notes-api Go 1.27 8080 Lead actor: multi-stage, scratch, hardening, secrets
notes-worker Python 3.13, uv – Multi-stage with uv (Day 6), runtime secrets (Day 14)
notes-web Node 24, Express 5 3000 Multi-stage with npm (Day 6), .npmrc as a secret (Day 13)

notes-api stores notes in memory. Anyone may read; only those who send the correct X-API-Key header may write. The code itself decides where the key comes from:

grep -n 'Getenv("NOTES_API_KEY' notes-api/main.go

Expected:

44:     if f := os.Getenv("NOTES_API_KEY_FILE"); f != "" {
51:     if k := os.Getenv("NOTES_API_KEY"); k != "" {

The file takes precedence over the variable. Day 14 explains why. And then there is the .env:

cat .env .env.example

Expected:

# Lokale Entwicklungswerte – Lab-Werte, niemals produktiv verwenden
NOTES_API_KEY=lab-api-key-123
# Vorlage: nach .env kopieren und Werte eintragen. Diese Datei darf ins Repository.
NOTES_API_KEY=

Security: lab-api-key-123 is a lab value. There is deliberately no .gitignore and no .dockerignore yet. You see what goes wrong because of that on Day 3 and Day 11, and on Day 12 you clean it up.

Save your progress? Sign up for free

Drill 7: The first build – the naive Dockerfile

cat notes-api/Dockerfile.naiv

Expected:

# syntax=docker/dockerfile:1
# Absichtlich schlecht – das Buch verbessert es Tag für Tag.
FROM golang:1.27
WORKDIR /src
COPY . .
ENV NOTES_API_KEY=lab-api-key-123
RUN go build -o /usr/local/bin/notes-api .
EXPOSE 8080
CMD notes-api

Take note of what strikes you about it. By the end of Day 15, none of these weaknesses will be left. Now build:

docker build -f notes-api/Dockerfile.naiv -t notes-api:naiv notes-api

Expected (abbreviated, may vary by version):

[+] Building 48.3s (11/11) FINISHED                              docker:colima
 => resolve image config for docker-image://docker.io/docker/dockerfile:1   1.2s
 => [internal] load build definition from Dockerfile.naiv                  0.0s
 => [internal] load metadata for docker.io/library/golang:1.27             1.1s
 => [1/4] FROM docker.io/library/golang:1.27@sha256:…                     31.5s
 => [internal] load build context                                          0.0s
 => [2/4] WORKDIR /src                                                     0.3s
 => [3/4] COPY . .                                                         0.0s
 => [4/4] RUN go build -o /usr/local/bin/notes-api .                      12.9s
 => exporting to image                                                     2.1s

 2 warnings found (use docker --debug to expand):
 - SecretsUsedInArgOrEnv: Do not use ARG or ENV instructions for sensitive data
   (ENV "NOTES_API_KEY") (line 6)
 - JSONArgsRecommended: JSON arguments recommended for CMD to prevent unintended
   behavior related to OS signals (line 9)

BuildKit already warns twice. Both warnings are lessons: the signal problem on Day 2, the key on Day 11. How big is the result?

docker image ls notes-api --format '{{.Repository}}:{{.Tag}}  {{.Size}}'

Expected (may vary by version):

notes-api:naiv  1.07GB

About a gigabyte for a program that is less than 10 MB as a binary. You find the reason in the layers on Day 1. Does it at least run?

docker run -d --name notes-api -p 127.0.0.1:8080:8080 notes-api:naiv
curl -s localhost:8080/healthz
curl -s -X POST localhost:8080/notes -H 'X-API-Key: lab-api-key-123' \
  -d '{"text":"Tag 0 geschafft"}'
curl -s localhost:8080/notes
docker logs notes-api

Expected (abbreviated, IDs and times differ):

ok
{"id":"6f1c…","text":"Tag 0 geschafft"}
[{"id":"6f1c…","text":"Tag 0 geschafft"}]
time=… level=INFO msg="api key loaded" source=env
time=… level=INFO msg=listening addr=:8080 version=dev pid=7

-p 127.0.0.1:8080:8080 publishes the port only on your Mac, not on the whole network. You do it this way throughout the book.

Save your progress? Sign up for free

Drill 8: A foretaste – the key is in the image

The application doesn’t log the key, only source=env. Still, anyone who has the image can read it:

docker history --no-trunc --format '{{.CreatedBy}}' notes-api:naiv | head -5
docker image inspect --format '{{json .Config.Env}}' notes-api:naiv | jq .

Expected (abbreviated, may vary by version):

CMD ["/bin/sh" "-c" "notes-api"]
EXPOSE map[8080/tcp:{}]
RUN /bin/sh -c go build -o /usr/local/bin/notes-api . # buildkit
ENV NOTES_API_KEY=lab-api-key-123
COPY . . # buildkit
[
  "PATH=/go/bin:/usr/local/go/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:…",
  "GOLANG_VERSION=1.27.…",
  "GOTOOLCHAIN=local",
  "GOPATH=/go",
  "NOTES_API_KEY=lab-api-key-123"
]

Two commands, no access to the source code, and the key is exposed. Anyone allowed to pull the image from a registry can also write to your API with it. And COPY . . put the .env into the image along with everything else:

docker run --rm notes-api:naiv cat /src/.env

Expected:

cat: /src/.env: No such file or directory

Lucky this time: the build context was notes-api/, and the .env sits one level higher. On Day 3 you build with the project folder as the context, and then it is in there. Day 11 shows all the ways a secret can get into an image.

Save your progress? Sign up for free

Drill 9: Reset and teardown

You only clean up what belongs to the lab: containers whose name starts with notes-, images whose name starts with notes- or localhost:5001/, and the cache of the builder docker-lab. Each time, produce a list and pass it to the delete command via xargs -r; -r makes xargs do nothing when the list is empty:

docker ps -a --filter name=^notes- --format '{{.Names}}' | xargs -r docker rm -f
docker image ls --format '{{.Repository}}:{{.Tag}}' \
  | grep -E '^(notes-|localhost:5001/)' | xargs -r docker rmi
docker buildx prune --builder docker-lab --all --force
docker image ls notes-api
curl -s http://localhost:5001/v2/

Expected (abbreviated, IDs and sizes differ):

notes-api
Untagged: notes-api:naiv
Deleted: sha256:687ddf973884…
Total:  0B
REPOSITORY   TAG       IMAGE ID   CREATED   SIZE
{}

These three lines come at the end of every day. The registry and builder keep running. If you want to tear everything down, including the registry volume and the builder:

docker rm -f docker-lab-registry
docker volume rm docker-lab-registry-data
docker buildx rm docker-lab

Next time you create both again as in Drill 4.

Tip: The base image golang:1.27 and the cache of the builder default stay around so the next build is faster. docker builder prune empties the cache of default, but for all projects on your machine. Use it only when docker system df shows you too much “Build Cache”.

Save your progress? Sign up for free

Checkpoint

source ~/docker-lab/setup/env.sh && echo "$REGISTRY $BUILDER"

Expected:

localhost:5001 docker-lab
docker ps --filter name=docker-lab-registry --format '{{.Names}} {{.Ports}}'

Expected:

docker-lab-registry 127.0.0.1:5001->5000/tcp
docker buildx ls | grep -c '^docker-lab '

Expected:

1
docker ps -a --filter name=^notes- --format '{{.Names}}' | wc -l

Expected:

0

Challenge

From Day 1 on you push images to the local registry. Build the naive image again, push it as localhost:5001/notes-api:naiv and then query the registry only via the HTTP API, without docker: Which repositories exist, which tags does notes-api have, and which digest belongs to the tag naiv?

Hint: The paths are /v2/_catalog, /v2/<repo>/tags/list and /v2/<repo>/manifests/<tag>. A HEAD request returns the digest in a header.

Solution

cd ~/docker-lab/notes
docker build -q -f notes-api/Dockerfile.naiv -t notes-api:naiv notes-api
docker tag notes-api:naiv localhost:5001/notes-api:naiv
docker push -q localhost:5001/notes-api:naiv

Expected (abbreviated, digests differ):

sha256:e9046573d5fd…
localhost:5001/notes-api:naiv

Which repositories are in the registry?

curl -s localhost:5001/v2/_catalog | jq

Expected:

{
  "repositories": [
    "notes-api"
  ]
}

Which tags does notes-api have?

curl -s localhost:5001/v2/notes-api/tags/list | jq

Expected:

{
  "name": "notes-api",
  "tags": [
    "naiv"
  ]
}

The digest is in the Docker-Content-Digest header. -I sends a HEAD request, which fetches only the headers:

curl -sI localhost:5001/v2/notes-api/manifests/naiv

Expected (abbreviated):

HTTP/1.1 200 OK
Content-Length: 856
Content-Type: application/vnd.oci.image.index.v1+json
Docker-Content-Digest: sha256:e9046573d5fd…
…

Content-Type shows the format: an OCI index. Other registries only return it if you request it with -H 'Accept: application/vnd.oci.image.index.v1+json'. For comparison, Docker’s view:

docker image ls --digests localhost:5001/notes-api

Expected (abbreviated, digests differ):

REPOSITORY                 TAG       DIGEST                    IMAGE ID       …
localhost:5001/notes-api   naiv      sha256:e9046573d5fd06d9…  e9046573d5fd   …

The same digest in the registry and in docker image ls --digests: a tag is a mutable name, the digest the immutable checksum of the manifest. On Day 8 and Day 10 you pin images by exactly this value. Finally, clean up:

docker ps -a --filter name=^notes- --format '{{.Names}}' | xargs -r docker rm -f
docker image ls --format '{{.Repository}}:{{.Tag}}' \
  | grep -E '^(notes-|localhost:5001/)' | xargs -r docker rmi
docker buildx prune --builder docker-lab --all --force

Tip: The registry keeps pushed images even after cleanup. That is intentional: it behaves like a real registry. Only docker volume rm docker-lab-registry-data (Drill 9) deletes them.

Save your progress? Sign up for free

Enterprise Note

  • Instead of a local registry without login: Harbor, Artifactory, Nexus, GHCR or ECR with authentication, robot accounts for CI and retention rules for old tags.
  • Base images come from a pull-through cache or mirror there, not directly from Docker Hub (rate limits, availability, control over provenance).
  • Builds run in CI on dedicated BuildKit instances or with remote builders. They share the cache via the registry (Day 4).
  • Colima and Docker Desktop are developer tools; Docker Desktop in larger companies requires a paid license, which is a common reason for Colima.
  • A Dockerfile like Dockerfile.naiv fails in the pipeline there: build checks, hadolint and a secret scan (Day 9, Day 11) abort the build.