Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 0: Das Trainingsgelände

Ziel: Docker mit BuildKit prüfen, lokale Registry und Builder starten, die Demo-Anwendung notes einrichten 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 (Builder default) oder docker buildx build (eigener Builder docker-lab für Cache-Export, Multi-Plattform und Attestations).
  • Eine lokale Registry auf localhost:5001 ersetzt Docker Hub, GHCR oder Harbor: Du pushst und ziehst Images, ohne ein Konto und ohne etwas zu veröffentlichen.
  • Die Demo-Anwendung notes hat 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 --version

Erwartet (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 version beim Server failed to connect to the docker API, läuft die VM nicht oder startet noch. Prüfe mit colima status, warte bis „colima is running” erscheint, und schau mit docker context ls, ob der Kontext colima aktiv 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 df

Erwartet (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 overlayfs heißt: Docker nutzt den containerd-Image-Store. Dann kann docker Multi-Plattform-Images und Attestations lokal halten (Tag 7, Tag 10). Steht dort overlay2, 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 -a rä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/setup

Erwartet:

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.sh

Erwartet:

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.sh

Fortschritt 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.0

Erwartet (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 ls

Erwartet (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/_catalog

Erwartet:

{"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 -1

Erwartet (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-web

Erwartet:

.:
.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.go

Erwartet:

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.example

Erwartet:

# 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-123 ist ein Lab-Wert. Es gibt bewusst noch keine .gitignore und 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.naiv

Erwartet:

# 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

Merk 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-api

Erwartet (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-api

Erwartet (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/.env

Erwartet:

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-lab

Beim nächsten Mal legst du beides wieder an wie in Drill 4.

Tipp: Das Base-Image golang:1.27 und der Cache des Builders default bleiben liegen, damit der nächste Build schneller ist. docker builder prune leert den Cache von default, aber für alle Projekte auf deinem Rechner. Nutze es nur, wenn dir docker system df zu 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 -l

Erwartet:

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:naiv

Erwartet (gekürzt, Digests weichen ab):

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

Welche Repositories liegen in der Registry?

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

Erwartet:

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

Welche Tags hat notes-api?

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

Erwartet:

{
  "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/naiv

Erwartet (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-api

Erwartet (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 --force

Tipp: 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.naiv fällt dort in der Pipeline durch: Build Checks, hadolint und ein Secret-Scan (Tag 9, Tag 11) brechen den Build ab.