Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 0: Das Trainingsgelände

Ziel: Docker und Compose prüfen, Begleitcode und Basis-Images einrichten, die Demo-Anwendung notes bauen und einmal komplett von Hand verdrahten – damit du weißt, was Compose dir ab morgen abnimmt. · Dauer: ca. 60 min · Voraussetzung: keine

Briefing

  • Docker läuft in einer kleinen Linux-VM von Colima. docker und docker compose auf dem Mac sprechen über einen Socket mit dem Daemon in der VM.
  • Compose ist ein Plugin der Docker-CLI. Es liest eine YAML-Datei und erledigt das, was du heute von Hand tippst: Netze, Volumes, Container, Reihenfolge.
  • Die Demo-Anwendung notes hat drei Dienste mit fertigen Dockerfiles aus „Dockerfiles zum Anfassen”. Neu: notes-api kann in Postgres speichern.
  • Heute gibt es noch keine compose.yaml. Die schreibst du an Tag 1.
 Mac                                   Colima-VM (Linux, arm64)
 ┌───────────────────────────┐         ┌──────────────────────────────────────┐
 │ ~/compose-lab/            │         │ Netz notes-net                       │
 │   setup/ env.sh           │  Socket │   notes-web ─► notes-api ─► notes-db │
 │   notes/ api worker web   │────────►│    :3000       :8080 ▲        │      │
 │   code/  Begleitcode      │  :8080  │                      │        │      │
 │   tagNN/ deine Arbeit     │  :3000  │           notes-worker        │      │
 │ docker, docker compose    │◄───────►│   Volume notes-pgdata ◄───────┘      │
 └───────────────────────────┘         └──────────────────────────────────────┘

Drill 1: Werkzeuge prüfen

docker version --format 'Client {{.Client.Version}} / Server {{.Server.Version}}'
docker compose version
docker buildx version
colima version | head -1
jq --version
curl --version | head -1

Erwartet (gekürzt, kann je nach Version abweichen):

Client 29.9.0 / Server 29.5.2
Docker Compose version 5.6.0
github.com/docker/buildx v0.38.0 Homebrew
colima version 0.10.3
jq-1.8.2
curl 8.7.1 (x86_64-apple-darwin24.0) libcurl/8.7.1 (SecureTransport) …

Fehlt etwas: brew install colima docker docker-compose docker-buildx jq. Compose ist seit Version 2 kein eigenes Programm docker-compose mehr, sondern das Unterkommando docker compose (mit Leerzeichen). Unter Linux genügt Docker Engine mit den Plugins für Compose und buildx, Docker Desktop funktioniert ebenfalls.

Achtung: Meldet docker version beim Server failed to connect to the docker API, läuft die VM nicht. Prüfe mit colima status und docker context ls, ob der Kontext colima aktiv ist (docker context use colima).

Fortschritt speichern? Kostenlos registrieren

Drill 2: Colima, Freigaben und Plattenplatz

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

Erwartet (gekürzt, Werte weichen bei dir ab):

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/disk3s5   228Gi   150Gi    11Gi    94%    1.9M  111M    2%   /System/Volumes/Data
TYPE            TOTAL     ACTIVE    SIZE      RECLAIMABLE
Images          3         1         5.667GB   506MB (8%)
Containers      1         1         24.58kB   0B (0%)
Local Volumes   18        1         2.926GB   2.853GB (97%)
Build Cache     156       0         5.184GB   5.184GB

Drei Dinge merkst du dir:

  • Freigaben: Colima gibt standardmäßig nur dein Home-Verzeichnis in die VM frei. Ein Bind-Mount aus /tmp oder /Volumes/… landet im Container als leerer Ordner, ohne Fehlermeldung. Deshalb liegt das Labor unter ~/compose-lab.
  • Storage overlayfs heißt: containerd-Image-Store. Images, die du baust, stehen sofort in docker image ls und sind für Compose nutzbar.
  • Freier Platz: Images, Build-Cache und Volumes leben in der VM-Disk von Colima. Halte mindestens 5 GB frei und räum nach jedem Tag gezielt auf (Drill 9).

Achtung: docker system prune und docker volume prune löschen auch die Daten anderer Projekte, zum Beispiel deren Datenbank-Volumes. Im Buch räumst du nur Lab-Spuren weg, gezielt über das Label lab=compose-lab (Drill 9).

Fortschritt speichern? Kostenlos registrieren

Drill 3: Arbeitsverzeichnis und Begleitcode

Den Begleitcode holst du einmal von GitHub nach ~/compose-lab/code. Setup-Datei und Demo-Anwendung bekommen eigene Kopien, damit du sie verändern kannst, ohne das Original zu verlieren:

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

Erwartet:

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

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

env.sh setzt nur Variablen, die alle Drills benutzen:

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

Erwartet:

export LAB="${LAB:-$HOME/compose-lab}"
export NOTES="$LAB/notes"
export LAB_LABEL="${LAB_LABEL:-compose-lab}"   # Label lab=… für docker run im Buch
export PROJECT="${COMPOSE_PROJECT_NAME:-notes}" # Compose-Projekt (name: notes)
export LAB_IMAGES="postgres:18.6-alpine golang:1.27-alpine python:3.15-slim \
node:26-alpine ghcr.io/astral-sh/uv:0.13.6"

LAB_IMAGES sind die Basis-Images des Buchs: Postgres als fertiger Dienst, die übrigen als Grundlage der drei Dockerfiles. Ab jetzt beginnt jeder Tag mit derselben Zeile:

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

Fortschritt speichern? Kostenlos registrieren

Drill 4: Basis-Images laden

Die Basis-Images lädst du einmal vorab, dann bauen die Tage schnell und ohne Rate-Limit-Überraschung. docker pull überspringt, was schon da ist:

for img in $LAB_IMAGES; do docker pull -q "$img"; done
docker image ls --format '{{.Repository}}:{{.Tag}}  {{.Size}}' \
  | grep -E '^(postgres|golang|python|node|ghcr.io/astral-sh/uv):'
df -h ~ | tail -1

Erwartet (gekürzt, Größen weichen ab):

docker.io/library/postgres:18.6-alpine
docker.io/library/golang:1.27-alpine
docker.io/library/python:3.15-slim
docker.io/library/node:26-alpine
ghcr.io/astral-sh/uv:0.13.6
node:26-alpine  252MB
python:3.15-slim  184MB
ghcr.io/astral-sh/uv:0.13.6  64.3MB
golang:1.27-alpine  382MB
postgres:18.6-alpine  433MB
/dev/disk3s1s1   228Gi    17Gi    11Gi    62%    426k  112M    0%   /

In der vierten Spalte von df stehen mindestens 5 GB.

Tipp: Getestet wurde mit golang:1.27-alpine (Go 1.27.3), python:3.15-slim (3.15.2), node:26-alpine (26.13.0) und postgres:18.6-alpine. Für golang:1.25 aus dem ersten Buch gibt es seit August 2026 keine Updates mehr; die Dockerfiles nutzen deshalb Go 1.27.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Die Demo-Anwendung kennenlernen

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

Erwartet:

.:
.dockerignore   .env.example    .hadolint.yaml  notes-web       README.md
.env            .gitignore      notes-api       notes-worker

notes-api:
.dockerignore   go.mod          main_test.go    metrics.go
Dockerfile      go.sum          main.go         store.go

notes-worker:
.dockerignore   Dockerfile      pyproject.toml  src             uv.lock

notes-web:
.dockerignore           package-lock.json       public                  src
Dockerfile              package.json            server.js
Dienst Sprache Port Rolle im Buch
notes-api Go 1.27 8080 Hauptdarsteller: Postgres, Healthcheck, Metriken
notes-worker Python 3.15, uv – liest regelmäßig alle Notizen über das API
notes-web Node 26, Express 5 3000 Oberfläche, leitet /api/notes an notes-api weiter
db Postgres 18.6 5432 fertiges Image, kein eigenes Dockerfile

Die Dockerfiles sind der Endstand aus „Dockerfiles zum Anfassen”: Multi-Stage, notes-api in scratch als User 65532 mit eingebautem HEALTHCHECK. Neu ist die Datenbank. Woher notes-api ihre Einstellungen nimmt, regelt der Code:

grep -n 'readSecret("NOTES' notes-api/main.go

Erwartet:

55: key, source, err = readSecret("NOTES_API_KEY")
64: return readSecret("NOTES_DB_URL")

readSecret liest zuerst die Datei aus <NAME>_FILE, sonst die Variable <NAME>. Für den API-Key ist das Pflicht. Die Datenbank ist optional:

  • ohne NOTES_DB_URL speichert notes-api im Speicher – wie im ersten Buch,
  • mit NOTES_DB_URL in Postgres. Beim Start prüft sie die Verbindung genau einmal; klappt das nicht, endet sie mit Exit-Code 1.
  • Die Tabelle legt nur das Unterkommando notes-api migrate an. Es ist idempotent, du kannst es beliebig oft ausführen.

Die Werte für das Labor stehen in .env, die Vorlage ohne Werte in .env.example:

cat .env.example

Erwartet:

# Vorlage: nach .env kopieren und Werte eintragen. Diese Datei darf ins Repository.
NOTES_API_KEY=
POSTGRES_PASSWORD=

Sicherheit: In .env stehen lab-api-key-123 und lab-db-pw-123, reine Lab-Werte. .gitignore und .dockerignore schließen .env bereits aus, das hast du im ersten Buch gelernt. An Tag 4 siehst du, dass Compose diese Datei trotzdem liest, und an Tag 10 verschwinden die Secrets aus ihr.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Drei Images bauen

cd ~/compose-lab/notes
for s in api worker web; do
  docker build -q -t "notes-${s}:tag00" "notes-${s}"
done
docker image ls --filter reference='notes-*' \
  --format '{{.Repository}}:{{.Tag}}  {{.Size}}'

Erwartet (gekürzt, Größen und IDs weichen bei dir ab):

sha256:df008224d81e…
sha256:eaa0ee28903b…
sha256:4f43fbfce3d6…
notes-web:tag00  266MB
notes-worker:tag00  214MB
notes-api:tag00  15.4MB

Der erste Durchlauf dauert einige Minuten, weil Go-Module, Python- und Node-Pakete geladen werden. -q zeigt nur die Image-ID. Ein schneller Test ohne Datenbank:

docker run --rm notes-api:tag00 migrate; echo "Exit: $?"

Erwartet (gekürzt, Zeiten weichen ab):

… level=ERROR msg="migration failed" err="NOTES_DB_URL oder NOTES_DB_URL_FILE fehlt"
Exit: 1

Ein sauberer Fehler mit Exit-Code ungleich 0. Genau darauf wird sich Compose an Tag 5 verlassen.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Von Hand verdrahtet – Netz, Postgres, Migration

So startest du den Stack ohne Compose. Zähl mit, wie viele Optionen du tippst.

docker network create --label lab=compose-lab notes-net
docker volume create --label lab=compose-lab notes-pgdata
docker run -d --name notes-db --label lab=compose-lab \
  --network notes-net --network-alias db \
  -e POSTGRES_USER=notes -e POSTGRES_DB=notes -e POSTGRES_PASSWORD=lab-db-pw-123 \
  -v notes-pgdata:/var/lib/postgresql postgres:18.6-alpine
until docker exec notes-db pg_isready -U notes -d notes; do sleep 1; done

Erwartet (gekürzt, IDs weichen ab):

0fdc0fb607f8…
notes-pgdata
88f2aa90c557…
/var/run/postgresql:5432 - no response
/var/run/postgresql:5432 - accepting connections
  • --network-alias db gibt dem Container im Netz notes-net den DNS-Namen db. Compose macht das später automatisch mit dem Dienstnamen.
  • Das Volume hängt an /var/lib/postgresql. Ab Postgres 18 liegen die Daten darunter in 18/docker; ältere Anleitungen mounten …/data und verlieren beim Upgrade oder bei docker rm ihre Daten (Tag 3).

Jetzt die Tabelle anlegen. migrate läuft als Einmal-Container und räumt sich mit --rm selbst weg:

DB_URL='postgres://notes:lab-db-pw-123@db:5432/notes'
docker run --rm --label lab=compose-lab --network notes-net \
  -e NOTES_DB_URL="$DB_URL" notes-api:tag00 migrate

Erwartet (gekürzt, Zeiten weichen ab):

time=… level=INFO msg="migration complete" table=notes

Fortschritt speichern? Kostenlos registrieren

Drill 8: api, worker und web dazu

docker run -d --name notes-api --label lab=compose-lab \
  --network notes-net --network-alias api -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 -e NOTES_DB_URL="$DB_URL" notes-api:tag00
docker run -d --name notes-worker --label lab=compose-lab --network notes-net \
  -e NOTES_API_URL=http://api:8080 -e NOTES_API_KEY=lab-api-key-123 notes-worker:tag00
docker run -d --name notes-web --label lab=compose-lab \
  --network notes-net -p 127.0.0.1:3000:3000 \
  -e NOTES_API_URL=http://api:8080 -e NOTES_API_KEY=lab-api-key-123 notes-web:tag00
sleep 3
docker ps --filter label=lab=compose-lab --format '{{.Names}}\t{{.Status}}'

Erwartet (gekürzt, IDs und Zeiten weichen ab):

2ff53a5c0586…
12c2c75ca425…
03449f811de0…
notes-web   Up 3 seconds
notes-worker    Up 3 seconds
notes-api   Up 3 seconds (healthy)
notes-db    Up 4 seconds

(healthy) kommt vom HEALTHCHECK im Image von notes-api; direkt nach dem Start steht dort kurz (health: starting), deshalb das sleep 3. Jetzt eine Notiz über die Oberfläche schreiben – notes-web hängt den Key selbst an – und direkt beim API lesen:

curl -s localhost:8080/healthz
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Tag 0 von Hand verdrahtet"}'; echo
curl -s localhost:8080/notes; echo
sleep 10
docker logs notes-api
docker logs notes-worker

Erwartet (gekürzt, IDs und Zeiten weichen ab):

ok
{"id":"299a5973-…","text":"Tag 0 von Hand verdrahtet"}
[{"id":"299a5973-…","text":"Tag 0 von Hand verdrahtet"}]
time=… level=INFO msg="api key loaded" source=env
time=… level=INFO msg="store ready" store=postgres
time=… level=INFO msg=listening addr=:8080 version=dev pid=1
worker started, api=http://api:8080, interval=10s
summary: 0 notes, 0 words
summary: 1 notes, 5 words

store=postgres: notes-api schreibt in die Datenbank. Die DB-URL mit dem Passwort taucht im Log nicht auf, nur die Quelle des Keys.

Fortschritt speichern? Kostenlos registrieren

Drill 9: Daten überleben den Container

Container sind Wegwerfware, das Volume nicht. Lösche Datenbank und API und starte beide neu – mit demselben Volume:

docker rm -f notes-api notes-db
docker run -d --name notes-db --label lab=compose-lab \
  --network notes-net --network-alias db \
  -e POSTGRES_USER=notes -e POSTGRES_DB=notes -e POSTGRES_PASSWORD=lab-db-pw-123 \
  -v notes-pgdata:/var/lib/postgresql postgres:18.6-alpine >/dev/null
until docker exec notes-db pg_isready -U notes -d notes >/dev/null; do sleep 1; done
docker run -d --name notes-api --label lab=compose-lab \
  --network notes-net --network-alias api -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 -e NOTES_DB_URL="$DB_URL" notes-api:tag00 >/dev/null
sleep 2
curl -s localhost:8080/notes; echo
docker exec notes-db psql -U notes -d notes -c 'SELECT text, created_at FROM notes'

Erwartet (gekürzt, IDs und Zeiten weichen ab):

notes-api
notes-db
[{"id":"299a5973-…","text":"Tag 0 von Hand verdrahtet"}]
           text            |          created_at
---------------------------+-------------------------------
 Tag 0 von Hand verdrahtet | 2026-10-29 20:23:47.997567+00
(1 row)

Die Notiz ist noch da. worker und web haben vom Neustart nichts gemerkt: Sie sprechen api über den DNS-Namen an, nicht über eine IP.

Bilanz: ein Netz, ein Volume, fünf docker run, rund 25 Optionen, eine Warteschleife, und die Reihenfolge stand nur in deinem Kopf. Ab Tag 1 steht all das in einer Datei. Zum Schluss räumst du ab, was du heute angelegt hast: vier Container, ein Netz, drei Images und das Volume, jeweils beim Namen:

docker rm -f notes-api notes-worker notes-web notes-db
docker network rm notes-net
docker image rm notes-api:tag00 notes-worker:tag00 notes-web:tag00
docker volume rm notes-pgdata

Erwartet (gekürzt, IDs weichen ab):

notes-api
notes-worker
notes-web
notes-db
notes-net
Untagged: notes-api:tag00
Deleted: sha256:462674996c48…
Untagged: notes-worker:tag00
Deleted: sha256:e6c41f02f0d5…
Untagged: notes-web:tag00
Deleted: sha256:90672b2e7e65…
notes-pgdata

Ab Tag 1 räumt docker compose down das alles mit einem Befehl auf. Die Basis-Images bleiben, die brauchst du morgen wieder.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

source ~/compose-lab/setup/env.sh && echo "$PROJECT $NOTES"

Erwartet:

notes /Users/du/compose-lab/notes
ls ~/compose-lab/notes/compose.yaml

Erwartet (die Datei schreibst du erst an Tag 1):

ls: /Users/du/compose-lab/notes/compose.yaml: No such file or directory
docker ps -a --filter label=lab=compose-lab --format '{{.Names}}' | wc -l

Erwartet:

0
docker volume ls --filter label=lab=compose-lab --format '{{.Name}}' | wc -l

Erwartet:

0

Challenge

Bisher hast du immer gewartet, bis Postgres bereit war. Starte auf einem frischen Volume notes-race die Datenbank und direkt danach notes-api, ohne Warteschleife. Was passiert mit notes-api, und wie liest du Ursache und Exit-Code ab, ohne den Container neu zu starten?

Hinweis: docker wait blockiert, bis ein Container endet, und gibt seinen Exit-Code aus; docker inspect kennt .State.ExitCode.

Lösung

cd ~/compose-lab/notes
docker build -q -t notes-api:tag00 notes-api >/dev/null
docker network create --label lab=compose-lab notes-net >/dev/null
docker volume create --label lab=compose-lab notes-race >/dev/null
DB_URL='postgres://notes:lab-db-pw-123@db:5432/notes'
docker run -d --name notes-db --label lab=compose-lab \
  --network notes-net --network-alias db \
  -e POSTGRES_USER=notes -e POSTGRES_DB=notes -e POSTGRES_PASSWORD=lab-db-pw-123 \
  -v notes-race:/var/lib/postgresql postgres:18.6-alpine >/dev/null
docker run -d --name notes-api --label lab=compose-lab \
  --network notes-net --network-alias api \
  -e NOTES_API_KEY=lab-api-key-123 -e NOTES_DB_URL="$DB_URL" notes-api:tag00 >/dev/null
docker wait notes-api
docker logs notes-api 2>&1 | tail -1
docker inspect -f '{{.State.Status}} exit={{.State.ExitCode}}' notes-api

Erwartet (gekürzt, Adressen und Zeiten weichen ab):

1
time=… level=ERROR msg="database unreachable" source=env err="failed to connect to
`user=notes database=notes`:\n\t172.20.0.2:5432 (db): dial error: dial tcp
172.20.0.2:5432: connect: connection refused…"
exited exit=1

Der Name db ließ sich auflösen – der Container existiert ja –, aber Postgres initialisierte noch und nahm auf TCP keine Verbindungen an. notes-api versucht es absichtlich nur einmal und endet mit Exit 1. Wer wartet, wer neu startet und woran „bereit” erkannt wird, regelt an Tag 5 Compose mit depends_on und Healthchecks. Zum Schluss aufräumen:

docker rm -f notes-api notes-db
docker network rm notes-net
docker image rm notes-api:tag00
docker volume rm notes-race

Erwartet (gekürzt, IDs weichen ab):

notes-api
notes-db
notes-net
Untagged: notes-api:tag00
Deleted: sha256:0eec1d688dc4…
notes-race

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Compose ist ein Werkzeug für einen einzelnen Docker-Host: Entwicklung, CI, kleine Server. Für mehrere Hosts, Selbstheilung über Knoten hinweg und Rollouts gibt es Kubernetes; die Begriffe (Service, Volume, Secret, Healthcheck) tragen weiter.
  • Basis-Images kommen in Firmen aus einem Spiegel oder Pull-Through-Cache (Harbor, Artifactory, Nexus), nicht direkt von Docker Hub – Rate-Limits und Herkunftskontrolle.
  • Docker Desktop braucht in größeren Firmen eine kostenpflichtige Lizenz; Colima, Rancher Desktop oder eine Linux-VM sind verbreitete Alternativen. Compose läuft auf allen.
  • Postgres im Container ist für Entwicklung, Tests und kleine Systeme gut. Für wichtige Daten zählen Backup, Restore-Tests und Upgrades mehr als der Ort, an dem der Prozess läuft (Tag 3).
  • Handverdrahtete docker run-Skripte wie heute findest du in vielen Altprojekten. Sie sind der häufigste Grund, auf Compose umzustellen: Die Datei ist versionierbar, prüfbar und für alle im Team gleich.