Tag 0: Das Trainingsgelände
Ziel: Docker und Compose prüfen, Begleitcode und Basis-Images einrichten, die Demo-Anwendung
notesbauen 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.
dockerunddocker composeauf 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
noteshat 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 -1Erwartet (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 versionbeim Serverfailed to connect to the docker API, läuft die VM nicht. Prüfe mitcolima statusunddocker context ls, ob der Kontextcolimaaktiv 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 dfErwartet (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
/tmpoder/Volumes/…landet im Container als leerer Ordner, ohne Fehlermeldung. Deshalb liegt das Labor unter~/compose-lab. - Storage
overlayfsheißt: containerd-Image-Store. Images, die du baust, stehen sofort indocker image lsund 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 pruneunddocker volume prunelöschen auch die Daten anderer Projekte, zum Beispiel deren Datenbank-Volumes. Im Buch räumst du nur Lab-Spuren weg, gezielt über das Labellab=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/setupErwartet:
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.shErwartet:
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.shFortschritt 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 -1Erwartet (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) undpostgres:18.6-alpine. Fürgolang:1.25aus 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-webErwartet:
.:
.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.goErwartet:
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_URLspeichert notes-api im Speicher – wie im ersten Buch, - mit
NOTES_DB_URLin 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 migratean. 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.exampleErwartet:
# Vorlage: nach .env kopieren und Werte eintragen. Diese Datei darf ins Repository.
NOTES_API_KEY=
POSTGRES_PASSWORD=
Sicherheit: In
.envstehenlab-api-key-123undlab-db-pw-123, reine Lab-Werte..gitignoreund.dockerignoreschließen.envbereits 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; doneErwartet (gekürzt, IDs weichen ab):
0fdc0fb607f8…
notes-pgdata
88f2aa90c557…
/var/run/postgresql:5432 - no response
/var/run/postgresql:5432 - accepting connections
--network-alias dbgibt dem Container im Netznotes-netden DNS-Namendb. Compose macht das später automatisch mit dem Dienstnamen.- Das Volume hängt an
/var/lib/postgresql. Ab Postgres 18 liegen die Daten darunter in18/docker; ältere Anleitungen mounten…/dataund verlieren beim Upgrade oder beidocker rmihre 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 migrateErwartet (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-workerErwartet (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-pgdataErwartet (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.yamlErwartet (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 -lErwartet:
0
docker volume ls --filter label=lab=compose-lab --format '{{.Name}}' | wc -lErwartet:
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-apiErwartet (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-raceErwartet (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.