Tag 0: Das Trainingsgelände
Ziel: Docker mit BuildKit prüfen, lokale Registry und Builder starten, die Demo-Anwendung
noteseinrichten und das naive Dockerfile ein erstes Mal bauen. · Dauer: ca. 45 min · Voraussetzung: keine
Briefing
- Docker läuft in einer kleinen Linux-VM von Colima.
Der
docker-Befehl auf dem Mac spricht über einen Socket mit dem Daemon in der VM. - Gebaut wird mit BuildKit, über
docker build(Builderdefault) oderdocker buildx build(eigener Builderdocker-labfür Cache-Export, Multi-Plattform und Attestations). - Eine lokale Registry auf
localhost:5001ersetzt Docker Hub, GHCR oder Harbor: Du pushst und ziehst Images, ohne ein Konto und ohne etwas zu veröffentlichen. - Die Demo-Anwendung
noteshat drei Dienste und ein absichtlich schlechtes Dockerfile, das du in den nächsten 15 Tagen verbesserst.
Mac Colima-VM (Linux, arm64)
┌──────────────────────────────┐ ┌───────────────────────────────────┐
│ ~/docker-lab/ │ Socket │ Docker-Daemon + BuildKit │
│ setup/ env.sh │ ─────────► │ Builder "default" │
│ notes/ api, worker, web │ │ Container "buildx_buildkit_ │
│ code/ Begleitcode │ │ docker-lab0" (Builder) │
│ tagNN/ deine Arbeit │ :5001 │ Container "docker-lab-registry" │
│ docker, buildx, hadolint ... │ ◄────────► │ registry:3.0.0 │
└──────────────────────────────┘ └───────────────────────────────────┘
Drill 1: Werkzeuge prüfen
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 --versionErwartet (gekürzt, kann je nach Version abweichen):
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
Fehlt etwas:
brew install colima docker docker-buildx docker-compose hadolint trivy shellcheck jq
und brew install goodwithtech/r/dockle (dockle liegt in
einem eigenen Tap). Unter Linux brauchst du Colima nicht, Docker Engine
mit buildx und Compose genügt; hadolint, trivy und dockle gibt es dort
als Release-Binary mit Prüfsummendatei, ShellCheck als Paket
shellcheck. Docker Desktop funktioniert ebenfalls, dann
ersetzt es Colima.
Achtung: Meldet
docker versionbeim Serverfailed to connect to the docker API, läuft die VM nicht oder startet noch. Prüfe mitcolima status, warte bis „colima is running” erscheint, und schau mitdocker context ls, ob der Kontextcolimaaktiv ist (docker context use colima).
Fortschritt speichern? Kostenlos registrieren
Drill 2: Colima, Image-Store und Plattenplatz
colima status
docker info --format 'Arch {{.Architecture}} · CPUs {{.NCPU}} · Storage {{.Driver}}'
df -h ~ | tail -1
docker system dfErwartet (gekürzt, kann je nach Version abweichen):
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
Zwei Werte merkst du dir:
- Storage
overlayfsheißt: Docker nutzt den containerd-Image-Store. Dann kanndockerMulti-Plattform-Images und Attestations lokal halten (Tag 7, Tag 10). Steht dortoverlay2, läuft der klassische Store; das Buch funktioniert trotzdem, du pushst solche Images dann direkt in die Registry statt sie lokal zu laden. - Freier Platz: Images, Build-Cache und Volumes leben in der VM-Disk von Colima, die wiederum Platz auf dem Mac belegt. Halte mindestens 5 GB frei und räum nach jedem Tag gezielt auf (Drill 9).
Achtung:
docker system prune -aräumt auch die Images und Caches anderer Projekte ab. Im Buch räumst du nur Lab-Spuren weg, mit den drei Befehlen aus Drill 9.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Arbeitsverzeichnis und Begleitcode
Den Begleitcode holst du einmal von GitHub nach
~/docker-lab/code. Setup-Datei und Demo-Anwendung bekommen
eigene Ordner, damit du sie verändern kannst, ohne das Original zu
verlieren:
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/setupErwartet:
Cloning into '/Users/du/docker-lab/code'...
/Users/du/docker-lab:
code notes setup tag00
/Users/du/docker-lab/setup:
env.sh
env.sh setzt nur Variablen, die alle Drills
benutzen:
grep -v '^#' ~/docker-lab/setup/env.shErwartet:
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"
Ab jetzt beginnt jeder Tag mit derselben Zeile:
source ~/docker-lab/setup/env.shFortschritt speichern? Kostenlos registrieren
Drill 4: Registry und Builder starten
Die Registry ist ein gewöhnlicher Container:
registry:3.0.0, nur auf 127.0.0.1:5001
erreichbar, mit einem Volume für die Daten.
--restart unless-stopped startet sie nach jedem Neustart
von Colima von selbst wieder.
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.0Erwartet (gekürzt, ID weicht ab):
Unable to find image 'registry:3.0.0' locally
…
Status: Downloaded newer image for registry:3.0.0
0b54e1a1002e…
Der Builder docker-lab läuft als eigener
BuildKit-Container (Treiber docker-container).
network=host lässt ihn die Registry unter
localhost:5001 erreichen, --bootstrap startet
ihn sofort statt beim ersten 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 lsErwartet (gekürzt, kann je nach Version abweichen):
#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
Der Stern bleibt bei default: Ohne
--builder docker-lab baut docker build weiter
mit dem eingebauten Builder, dessen Images sofort in
docker image ls stehen. Den Builder docker-lab
nimmst du nur, wenn ein Tag es sagt.
Die Registry spricht die OCI-Distribution-API, du kannst sie mit
curl fragen:
curl -s http://localhost:5001/v2/_catalogErwartet:
{"repositories":[]}
Beide Befehle legen nur an, was fehlt: Läuft die Registry schon,
meldet docker run einen Namenskonflikt, gibt es den Builder
schon, lehnt buildx create ab. Beides kannst du
ignorieren.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Gelände prüfen
Dieselben Prüfungen machst du, wenn später etwas klemmt. Erst die Registry, dann der 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):'Erwartet:
200
Name: docker-lab
Driver: docker-container
Name: docker-lab0
Status: running
000 statt 200 heißt: Die Registry läuft
nicht, docker start docker-lab-registry holt sie zurück.
Steht beim Builder inactive oder stopped,
startet ihn der nächste Build mit --builder docker-lab von
selbst. Zum Schluss Werkzeuge, Demo-Anwendung und Plattenplatz:
command -v hadolint trivy jq
ls "$NOTES/notes-api/main.go"
df -h ~ | tail -1Erwartet (gekürzt, Pfade und Größen weichen ab):
/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% /
In der vierten Spalte stehen mindestens 5 GB.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Die Demo-Anwendung kennenlernen
cd ~/docker-lab/notes
ls -A . notes-api notes-worker notes-webErwartet:
.:
.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
| Dienst | Sprache | Port | Rolle im Buch |
|---|---|---|---|
notes-api |
Go 1.27 | 8080 | Hauptdarsteller: Multi-Stage, scratch, Härtung, Secrets |
notes-worker |
Python 3.13, uv | – | Multi-Stage mit uv (Tag 6), Laufzeit-Secrets (Tag 14) |
notes-web |
Node 24, Express 5 | 3000 | Multi-Stage mit npm (Tag 6), .npmrc als Secret (Tag
13) |
notes-api speichert Notizen im Speicher. Lesen darf
jeder, schreiben nur, wer den richtigen Header X-API-Key
mitschickt. Woher der Key kommt, regelt der Code selbst:
grep -n 'Getenv("NOTES_API_KEY' notes-api/main.goErwartet:
44: if f := os.Getenv("NOTES_API_KEY_FILE"); f != "" {
51: if k := os.Getenv("NOTES_API_KEY"); k != "" {
Die Datei hat Vorrang vor der Variablen. Warum, klärt Tag 14. Und
dann ist da noch die .env:
cat .env .env.exampleErwartet:
# 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=
Sicherheit:
lab-api-key-123ist ein Lab-Wert. Es gibt bewusst noch keine.gitignoreund keine.dockerignore. Was dadurch schiefgeht, siehst du an Tag 3 und Tag 11, und an Tag 12 räumst du es auf.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Der erste Build – das naive Dockerfile
cat notes-api/Dockerfile.naivErwartet:
# 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-apiMerk dir, was dir daran auffällt. Am Ende von Tag 15 ist keine dieser Schwächen mehr übrig. Jetzt bauen:
docker build -f notes-api/Dockerfile.naiv -t notes-api:naiv notes-apiErwartet (gekürzt, kann je nach Version abweichen):
[+] 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 warnt schon jetzt zweimal. Beide Warnungen sind Lektionen: das Signal-Problem an Tag 2, der Key an Tag 11. Wie groß ist das Ergebnis?
docker image ls notes-api --format '{{.Repository}}:{{.Tag}} {{.Size}}'Erwartet (kann je nach Version abweichen):
notes-api:naiv 1.07GB
Rund ein Gigabyte für ein Programm, das als Binary keine 10 MB groß ist. Den Grund findest du an Tag 1 in den Layern. Läuft es wenigstens?
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-apiErwartet (gekürzt, IDs und Zeiten weichen ab):
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 veröffentlicht den Port nur auf
deinem Mac, nicht im ganzen Netz. Das machst du im ganzen Buch so.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Vorgeschmack – der Key steckt im Image
Die Anwendung loggt den Key nicht, nur source=env.
Trotzdem liest ihn jeder, der das Image hat:
docker history --no-trunc --format '{{.CreatedBy}}' notes-api:naiv | head -5
docker image inspect --format '{{json .Config.Env}}' notes-api:naiv | jq .Erwartet (gekürzt, kann je nach Version abweichen):
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"
]
Zwei Befehle, kein Zugriff auf den Quellcode, und der Key liegt
offen. Wer das Image aus einer Registry ziehen darf, darf damit auch in
deine API schreiben. Und COPY . . hat die .env
gleich mit ins Image gelegt:
docker run --rm notes-api:naiv cat /src/.envErwartet:
cat: /src/.env: No such file or directory
Diesmal noch Glück: Der Build-Kontext war notes-api/,
die .env liegt eine Ebene höher. An Tag 3 baust du mit dem
Projektordner als Kontext, dann ist sie drin. Tag 11 zeigt alle Wege,
auf denen ein Secret in ein Image gerät.
Fortschritt speichern? Kostenlos registrieren
Drill 9: Reset und Abbau
Aufgeräumt wird nur, was zum Labor gehört: Container, deren Name mit
notes- beginnt, Images, deren Name mit notes-
oder localhost:5001/ beginnt, und der Cache des Builders
docker-lab. Jeweils eine Liste erzeugen und per
xargs -r an den Löschbefehl geben; -r lässt
xargs bei leerer Liste nichts tun:
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/Erwartet (gekürzt, IDs und Größen weichen ab):
notes-api
Untagged: notes-api:naiv
Deleted: sha256:687ddf973884…
Total: 0B
REPOSITORY TAG IMAGE ID CREATED SIZE
{}
Diese drei Zeilen stehen am Ende jedes Tages. Registry und Builder laufen weiter. Willst du alles abbauen, auch Registry-Volume und Builder:
docker rm -f docker-lab-registry
docker volume rm docker-lab-registry-data
docker buildx rm docker-labBeim nächsten Mal legst du beides wieder an wie in Drill 4.
Tipp: Das Base-Image
golang:1.27und der Cache des Buildersdefaultbleiben liegen, damit der nächste Build schneller ist.docker builder pruneleert den Cache vondefault, aber für alle Projekte auf deinem Rechner. Nutze es nur, wenn dirdocker system dfzu viel „Build Cache” zeigt.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
source ~/docker-lab/setup/env.sh && echo "$REGISTRY $BUILDER"Erwartet:
localhost:5001 docker-lab
docker ps --filter name=docker-lab-registry --format '{{.Names}} {{.Ports}}'Erwartet:
docker-lab-registry 127.0.0.1:5001->5000/tcp
docker buildx ls | grep -c '^docker-lab 'Erwartet:
1
docker ps -a --filter name=^notes- --format '{{.Names}}' | wc -lErwartet:
0
Challenge
Ab Tag 1 pushst du Images in die lokale Registry. Bau das naive Image
erneut, push es als localhost:5001/notes-api:naiv und frag
die Registry dann nur per HTTP-API, ohne docker: Welche
Repositories gibt es, welche Tags hat notes-api, und
welcher Digest gehört zum Tag naiv?
Hinweis: Die Pfade heißen /v2/_catalog,
/v2/<repo>/tags/list und
/v2/<repo>/manifests/<tag>. Den Digest liefert
ein HEAD-Request im Header.
Lösung
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:naivErwartet (gekürzt, Digests weichen ab):
sha256:e9046573d5fd…
localhost:5001/notes-api:naiv
Welche Repositories liegen in der Registry?
curl -s localhost:5001/v2/_catalog | jqErwartet:
{
"repositories": [
"notes-api"
]
}
Welche Tags hat notes-api?
curl -s localhost:5001/v2/notes-api/tags/list | jqErwartet:
{
"name": "notes-api",
"tags": [
"naiv"
]
}
Der Digest steht im Header Docker-Content-Digest.
-I schickt einen HEAD-Request, der nur die
Header holt:
curl -sI localhost:5001/v2/notes-api/manifests/naivErwartet (gekürzt):
HTTP/1.1 200 OK
Content-Length: 856
Content-Type: application/vnd.oci.image.index.v1+json
Docker-Content-Digest: sha256:e9046573d5fd…
…
Content-Type zeigt das Format: ein OCI-Index. Andere
Registries liefern ihn nur, wenn du ihn mit
-H 'Accept: application/vnd.oci.image.index.v1+json'
anforderst. Zum Vergleich die Sicht von Docker:
docker image ls --digests localhost:5001/notes-apiErwartet (gekürzt, Digests weichen ab):
REPOSITORY TAG DIGEST IMAGE ID …
localhost:5001/notes-api naiv sha256:e9046573d5fd06d9… e9046573d5fd …
Derselbe Digest in der Registry und bei
docker image ls --digests: Ein Tag ist ein veränderlicher
Name, der Digest die unveränderliche Prüfsumme des Manifests. An Tag 8
und Tag 10 pinnst du Images genau über diesen Wert. Zum Schluss
aufräumen:
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 --forceTipp: Die Registry behält gepushte Images auch nach dem Aufräumen. Das ist Absicht: Sie verhält sich wie eine echte Registry. Erst
docker volume rm docker-lab-registry-data(Drill 9) löscht sie.
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- Statt einer lokalen Registry ohne Login: Harbor, Artifactory, Nexus, GHCR oder ECR mit Authentifizierung, Robot-Accounts für CI und Retention-Regeln für alte Tags.
- Base-Images kommen dort aus einem Pull-Through-Cache oder Spiegel, nicht direkt von Docker Hub (Rate-Limits, Verfügbarkeit, Kontrolle über die Herkunft).
- Builds laufen in CI auf eigenen BuildKit-Instanzen oder mit Remote-Buildern. Den Cache teilen sie über die Registry (Tag 4).
- Colima und Docker Desktop sind Entwickler-Werkzeuge; für Docker Desktop in größeren Firmen gilt eine kostenpflichtige Lizenz, das ist ein häufiger Grund für Colima.
- Ein Dockerfile wie
Dockerfile.naivfällt dort in der Pipeline durch: Build Checks, hadolint und ein Secret-Scan (Tag 9, Tag 11) brechen den Build ab.