Day 0: The Training Ground
Goal: Check Docker with BuildKit, start a local registry and builder, set up the demo application
notesand 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
dockercommand on the Mac talks to the daemon in the VM over a socket. - Builds use BuildKit, via
docker build(builderdefault) ordocker buildx build(a dedicated builderdocker-labfor cache export, multi-platform and attestations). - A local registry on
localhost:5001replaces Docker Hub, GHCR or Harbor: you push and pull images without an account and without publishing anything. - The demo application
noteshas 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 --versionExpected (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 versionreportsfailed to connect to the docker APIfor the server, the VM isn’t running or is still starting. Check withcolima status, wait until “colima is running” appears, and usedocker context lsto see whether the contextcolimais 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 dfExpected (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
overlayfsmeans: Docker uses the containerd image store. Thendockercan keep multi-platform images and attestations locally (Day 7, Day 10). If it saysoverlay2, 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 -aalso 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/setupExpected:
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.shExpected:
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.shSave 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.0Expected (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 lsExpected (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/_catalogExpected:
{"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 -1Expected (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-webExpected:
.:
.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.goExpected:
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.exampleExpected:
# 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-123is a lab value. There is deliberately no.gitignoreand no.dockerignoreyet. 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.naivExpected:
# 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-apiTake 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-apiExpected (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-apiExpected (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/.envExpected:
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-labNext time you create both again as in Drill 4.
Tip: The base image
golang:1.27and the cache of the builderdefaultstay around so the next build is faster.docker builder pruneempties the cache ofdefault, but for all projects on your machine. Use it only whendocker system dfshows 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 -lExpected:
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:naivExpected (abbreviated, digests differ):
sha256:e9046573d5fd…
localhost:5001/notes-api:naiv
Which repositories are in the registry?
curl -s localhost:5001/v2/_catalog | jqExpected:
{
"repositories": [
"notes-api"
]
}
Which tags does notes-api have?
curl -s localhost:5001/v2/notes-api/tags/list | jqExpected:
{
"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/naivExpected (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-apiExpected (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 --forceTip: 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.naivfails in the pipeline there: build checks, hadolint and a secret scan (Day 9, Day 11) abort the build.