Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Die erste compose.yaml

Ziel: Den Stack aus Tag 0 (noch ohne Datenbank) als eine compose.yaml beschreiben, mit einem Befehl starten, beobachten und wieder abräumen. · Dauer: ca. 60 min · Voraussetzung: Tag 0

Briefing

  • Eine compose.yaml beschreibt Services. Compose macht daraus Container, ein Netz und, bei build:, die Images.
  • build: baut aus einem Ordner mit Dockerfile, image: nimmt ein fertiges Image.
  • Alles gehört zu einem Projekt. Sein Name steckt in jedem Container-, Netz- und Image-Namen: notes-api-1, notes_default, notes-api.
  • Heute läuft notes-api im Speicherbetrieb. Postgres kommt an Tag 3.
 Mac 127.0.0.1                    Projekt notes, Netz notes_default
 ┌────────────┐  :3000  ┌──────────────┐  http://api:8080  ┌──────────────┐
 │ curl       │────────►│ notes-web-1  │──────────────────►│ notes-api-1  │
 │            │  :8080  └──────────────┘                   │  (Speicher)  │
 │            │───────────────────────────────────────────►│              │
 └────────────┘                         ┌──────────────┐   └──────▲───────┘
                                        │notes-worker-1│──────────┘
                                        └──────────────┘

Drill 1: Die erste Datei, ein Dienst

Tagesstart wie immer, heute nur mit der Demo-Anwendung als Ausgangsstand:

source ~/compose-lab/setup/env.sh
mkdir -p ~/compose-lab/tag01 && cd ~/compose-lab/tag01
cp -R "$LAB/code/notes/." .

Zuerst nur notes-api:

cat > compose.yaml <<'EOF'
# compose.yaml – erster Versuch: nur api
name: notes

services:
  api:
    build: notes-api
    environment:
      NOTES_API_KEY: ${NOTES_API_KEY}
    ports:
      - "127.0.0.1:${API_PORT:-8080}:8080"
EOF
docker compose up -d
docker compose ps
curl -s localhost:8080/healthz; echo

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

 Image notes-api Built
 Network notes_default Created
 Container notes-api-1 Started
NAME          IMAGE       COMMAND        SERVICE   CREATED        STATUS     …   PORTS
notes-api-1   notes-api   "/notes-api"   api       1 second ago   Up Less than a second
  (health: starting)   127.0.0.1:8080->8080/tcp
ok
  • build: notes-api ist die Kurzform für den Build-Kontext; das Dockerfile darin wird benutzt. Tag 8 zeigt die lange Form.
  • ${NOTES_API_KEY} kommt aus .env im Projektordner, Compose liest sie automatisch.
  • "127.0.0.1:${API_PORT:-8080}:8080": Host-Adresse, Host-Port, Container-Port. ${API_PORT:-8080} heißt „API_PORT, sonst 8080”. Die Adresse 127.0.0.1 hält den Port vom Netz fern (Tag 4 erklärt die Variablen im Detail).

Im Terminal zeigt Compose die Schritte als Fortschrittsanzeige mit Haken; das Ergebnis ist dasselbe.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Drei Dienste in einer Datei

Jetzt der ganze Stack von Tag 0, ohne Datenbank:

cat > compose.yaml <<'EOF'
# compose.yaml – Stand Ende Tag 1
name: notes

services:
  api:
    build: notes-api
    environment:
      NOTES_API_KEY: ${NOTES_API_KEY}
    ports:
      - "127.0.0.1:${API_PORT:-8080}:8080"

  worker:
    build: notes-worker
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY}
    depends_on:
      - api

  web:
    build: notes-web
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY}
    ports:
      - "127.0.0.1:${WEB_PORT:-3000}:3000"
    depends_on:
      - api
EOF
docker compose up -d

Erwartet (gekürzt):

 Image notes-worker Built
 Image notes-web Built
 Container notes-api-1 Running
 Container notes-worker-1 Created
 Container notes-web-1 Created
 Container notes-worker-1 Started
 Container notes-web-1 Started

api lief schon und passt zur Datei, also lässt Compose ihn in Ruhe (Running). Nur die neuen Dienste werden gebaut und gestartet. depends_on sorgt dafür, dass api vor worker und web startet – gestartet, nicht bereit (Tag 5).

docker compose ps --format 'table {{.Service}}\t{{.Name}}\t{{.Status}}\t{{.Ports}}'
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Tag 1 mit Compose"}'; echo
curl -s localhost:8080/notes; echo

Erwartet (gekürzt):

SERVICE   NAME             STATUS                    PORTS
api       notes-api-1      Up 14 seconds (healthy)   127.0.0.1:8080->8080/tcp
web       notes-web-1      Up 7 seconds              127.0.0.1:3000->3000/tcp
worker    notes-worker-1   Up 7 seconds
{"id":"ff3372ac-…","text":"Tag 1 mit Compose"}
[{"id":"ff3372ac-…","text":"Tag 1 mit Compose"}]

Vergleich mit Tag 0: kein docker network create, kein --network-alias. worker und web erreichen http://api:8080, weil Compose jeden Dienst unter seinem Namen ins Netz hängt (Tag 2).

Fortschritt speichern? Kostenlos registrieren

Drill 3: Logs aller Dienste

docker compose logs --tail 3

Erwartet (gekürzt):

api-1     | time=… level=INFO msg="api key loaded" source=env
api-1     | time=… level=INFO msg="store ready" store=memory
worker-1  | worker started, api=http://api:8080, interval=10s
worker-1  | summary: 0 notes, 0 words
worker-1  | summary: 1 notes, 4 words
api-1     | time=… level=INFO msg=listening addr=:8080 version=dev pid=1
web-1     | notes-web listening on :3000

--tail 3 gilt pro Dienst, die Zeilen sind nach Zeit gemischt, der Präfix nennt Dienst und Nummer. store=memory: ohne NOTES_DB_URL speichert notes-api im Speicher. Einem Dienst live folgen, Ende mit Strg+C:

docker compose logs -f worker

Erwartet (gekürzt):

worker-1  | summary: 1 notes, 4 words
worker-1  | summary: 1 notes, 4 words
^C

Fortschritt speichern? Kostenlos registrieren

Drill 4: Was Compose angelegt hat

docker network ls --filter label=com.docker.compose.project=notes \
  --format '{{.Name}}  {{.Driver}}'
docker image ls --filter reference='notes-*' \
  --format '{{.Repository}}:{{.Tag}}  {{.Size}}'
docker ps --filter label=com.docker.compose.project=notes --format \
  '{{.Names}}  service={{.Label "com.docker.compose.service"}}'
docker compose ls

Erwartet (gekürzt):

notes_default  bridge
notes-web:latest  266MB
notes-worker:latest  214MB
notes-api:latest  15.4MB
notes-web-1  service=web
notes-worker-1  service=worker
notes-api-1  service=api
NAME     STATUS       CONFIG FILES
notes    running(3)   /Users/du/compose-lab/tag01/compose.yaml
Objekt Schema Beispiel
Container <projekt>-<dienst>-<nummer> notes-api-1
Netz <projekt>_<netz> notes_default
Image (build:, kein image:) <projekt>-<dienst>:latest notes-api:latest

Compose findet „seine” Objekte über Labels wie com.docker.compose.project – darauf kannst du auch selbst filtern (--filter label=com.docker.compose.project=notes). Deshalb gibt es im Buch kein container_name:: Ein fester Name verhindert zweite Instanzen und Skalierung.

Woher kommt notes? Laut Doku gilt, von oben nach unten: -p, dann COMPOSE_PROJECT_NAME, dann name: in der Datei, sonst der Name des Projektordners. Mit --dry-run zeigt Compose, was es täte, ohne etwas anzulegen:

docker compose --dry-run up -d 2>&1 | grep -m1 Network
docker compose -p demo --dry-run up -d 2>&1 | grep -m1 Network
COMPOSE_PROJECT_NAME=demo2 docker compose --dry-run up -d 2>&1 | grep -m1 Network
sed '/^name: /d' compose.yaml > ohne-name.yaml
docker compose -f ohne-name.yaml --dry-run up -d 2>&1 | grep -m1 Network
rm ohne-name.yaml

Erwartet:

 Network notes_default Creating
 Network demo_default Creating
 Network demo2_default Creating
 Network tag01_default Creating

Ohne name: hieße das Projekt nach dem Ordner tag01 – und jeder Tag wäre ein eigenes Projekt. name: notes macht den Namen unabhängig vom Ordner.

Fortschritt speichern? Kostenlos registrieren

Drill 5: config – die Datei, wie Compose sie sieht

docker compose config liest alle Dateien, setzt Variablen ein, ergänzt Standardwerte und gibt das Ergebnis aus – oder einen Fehler, bevor etwas startet:

docker compose config
API_PORT=8081 docker compose config | grep -A4 'ports:' | head -5
docker compose config -q; echo "Exit: $?"

Was du siehst: Der erste Befehl gibt die vollständige Datei aus, mit eingesetzten Werten und ergänzten Standards wie dem Projektnamen name: notes und dem Netz default. Der zweite zeigt den Port-Eintrag in Langform, mit 8081 als veröffentlichtem Port. Der dritte meldet nur Exit: 0: -q gibt nichts aus und prüft allein über den Exit-Code.

Sicherheit: config zeigt die eingesetzten Werte, also auch den API-Key aus .env. Die Ausgabe gehört nicht in Tickets oder CI-Logs (Tag 4).

Fortschritt speichern? Kostenlos registrieren

Drill 6: exec und run --rm

exec startet einen Befehl in einem laufenden Container eines Dienstes:

docker compose exec web wget -qO- http://api:8080/healthz; echo
docker compose exec web id
docker compose exec api sh; echo "Exit: $?"
docker compose exec api /notes-api healthcheck; echo "Exit: $?"

Erwartet:

ok
uid=1000(node) gid=1000(node) groups=1000(node)
OCI runtime exec failed: exec failed: unable to start container process: exec: "sh":
executable file not found in $PATH
Exit: 127
Exit: 0

notes-api läuft in scratch: keine Shell, nur das eigene Programm. web aus node:26-alpine bringt BusyBox mit, ideal für Netztests. run --rm startet dagegen einen neuen Einmal-Container mit der Konfiguration des Dienstes:

docker compose run --rm api migrate; echo "Exit: $?"
docker compose run --rm --no-deps web \
  node -e 'console.log(process.version, process.env.NOTES_API_URL)'
docker compose ps -a --format '{{.Name}}  {{.Status}}'

Erwartet (gekürzt):

 Container notes-api-run-edc4062ed3d1 Created
time=… level=ERROR msg="migration failed" err="NOTES_DB_URL oder NOTES_DB_URL_FILE …"
Exit: 1
 Container notes-web-run-03da83ceab73 Created
v26.13.0 http://api:8080
notes-api-1  Up 40 seconds (healthy)
notes-web-1  Up 33 seconds
notes-worker-1  Up 33 seconds
  • Der Einmal-Container heißt <projekt>-<dienst>-run-<id> und ist nach --rm weg.
  • Er bekommt Umgebung und Netz des Dienstes, aber keine ports: (dafür gibt es --service-ports), sonst kollidierte er mit dem laufenden Container.
  • --no-deps startet keine Abhängigkeiten mit. migrate scheitert heute sauber – an Tag 3 legt genau dieser Befehl die Tabelle an.

Fortschritt speichern? Kostenlos registrieren

Drill 7: Lebenszyklus – stop, start, restart, down

curl -s localhost:8080/notes; echo
docker compose stop
docker compose ps -a --format '{{.Name}}  {{.Status}}'
docker compose start
sleep 2; curl -s localhost:8080/notes; echo

Erwartet (gekürzt):

[{"id":"ff3372ac-…","text":"Tag 1 mit Compose"}]
 Container notes-worker-1 Stopped
 Container notes-web-1 Stopped
 Container notes-api-1 Stopped
notes-api-1  Exited (0) Less than a second ago
notes-web-1  Exited (0) Less than a second ago
notes-worker-1  Exited (0) Less than a second ago
 Container notes-api-1 Started
 Container notes-worker-1 Started
 Container notes-web-1 Started
[]

stop hält in umgekehrter Abhängigkeitsreihenfolge an (erst worker und web, dann api), start startet api zuerst. Die Container bleiben erhalten – die Notiz nicht: Sie lag im Speicher des Prozesses. Dasselbe passiert bei restart:

docker compose restart api
docker compose logs api --no-log-prefix | tail -4

Erwartet (gekürzt):

 Container notes-api-1 Restarting
 Container notes-api-1 Started
time=… level=INFO msg="shutdown complete"
time=… level=INFO msg="api key loaded" source=env
time=… level=INFO msg="store ready" store=memory
time=… level=INFO msg=listening addr=:8080 version=dev pid=1

down dagegen entfernt Container und Netz, die Images bleiben:

docker compose down
docker compose ps -a
docker image ls --filter reference='notes-*' --format '{{.Repository}}'

Erwartet (gekürzt):

 Container notes-web-1 Removed
 Container notes-worker-1 Removed
 Container notes-api-1 Removed
 Network notes_default Removed
NAME      IMAGE     COMMAND   SERVICE   CREATED   STATUS    PORTS
notes-web
notes-worker
notes-api
Befehl Container Netz Images
stop / start / restart bleiben bleibt bleiben
down entfernt entfernt bleiben
down --rmi local entfernt entfernt gebaute entfernt

Fortschritt speichern? Kostenlos registrieren

Drill 8: Änderungen übernehmen

up -d vergleicht Datei und Variablen mit den laufenden Containern und ersetzt nur, was sich geändert hat:

docker compose up -d >/dev/null 2>&1
API_PORT=8081 docker compose up -d
docker compose ps --format '{{.Service}}  {{.Ports}}'
curl -s localhost:8081/healthz; echo
docker compose up -d

Erwartet:

 Container notes-worker-1 Running
 Container notes-web-1 Running
 Container notes-api-1 Recreate
 Container notes-api-1 Recreated
 Container notes-api-1 Started
api  127.0.0.1:8081->8080/tcp
web  127.0.0.1:3000->3000/tcp
worker
ok
 Container notes-web-1 Running
 Container notes-worker-1 Running
 Container notes-api-1 Recreate
 Container notes-api-1 Recreated
 Container notes-api-1 Started

Code-Änderungen sieht up -d dagegen nicht, denn das Image existiert ja schon:

sed -i '' 's|<h1>notes</h1>|<h1>notes – Tag 1</h1>|' notes-web/public/index.html
docker compose up -d
curl -s localhost:3000/ | grep '<h1>'
docker compose up -d --build
sleep 2; curl -s localhost:3000/ | grep '<h1>'

Erwartet (gekürzt):

 Container notes-worker-1 Running
 Container notes-web-1 Running
 Container notes-api-1 Running
  <h1>notes</h1>
 Image notes-api Built
 Image notes-web Built
 Image notes-worker Built
 Container notes-api-1 Running
 Container notes-web-1 Recreated
 Container notes-worker-1 Recreated
  <h1>notes – Tag 1</h1>

--build baut alle Images und ersetzt jeden Container, dessen Image danach eine neue ID hat. Im Testlauf traf das auch worker, obwohl sich an ihm nichts geändert hatte: Ein neuer Build kann trotz Cache eine neue Image-ID liefern. (Unter Linux heißt es sed -i ohne ''.) Änderung zurücknehmen und nur web neu bauen:

sed -i '' 's|<h1>notes – Tag 1</h1>|<h1>notes</h1>|' notes-web/public/index.html
docker compose up -d --build web

Erwartet (gekürzt):

 Image notes-api Built
 Image notes-web Built
 Container notes-api-1 Running
 Container notes-web-1 Recreated
 Container notes-web-1 Started

Mit Dienstnamen baut Compose diesen Dienst und seine Abhängigkeiten (api), ersetzt aber nur den Container von web.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Der Stack läuft (docker compose up -d). Der Projektname steht in der Datei:

cd ~/compose-lab/tag01
grep '^name:' compose.yaml

Erwartet:

name: notes

Drei Dienste laufen:

docker compose ps --format '{{.Service}} {{.State}}'

Erwartet:

api running
web running
worker running

Das Netz notes_default und die drei Images:

docker network ls --filter name=notes_default --format '{{.Name}}'
docker image ls --filter reference='notes-*' --format '{{.Repository}}'

Erwartet (Reihenfolge kann abweichen):

notes_default
notes-web
notes-worker
notes-api

api antwortet auf 127.0.0.1:8080:

curl -s localhost:8080/healthz

Erwartet:

ok

Eine Notiz über web schreiben, über api lesen:

curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"Kontrollpunkt Tag 1"}'
curl -s localhost:8080/notes | jq -r '.[].text'

Erwartet (gekürzt, ID weicht ab):

{"id":"54a84d46-…","text":"Kontrollpunkt Tag 1"}
Kontrollpunkt Tag 1

worker fasst zusammen:

docker compose logs worker | tail -1

Erwartet (gekürzt):

worker-1  | summary: 0 notes, 0 words

Die vollständige Datei liegt in code/tag01/notes/compose.yaml.

Challenge

Eine Kollegin will den Stack parallel zu deinem testen – aus demselben Ordner, mit derselben Datei, ohne sie zu ändern. Starte eine zweite Instanz notes2 auf den Ports 8081 und 3001, zeige, dass beide Instanzen getrennte Daten haben, und entferne notes2 danach samt ihrer Images.

Hinweis: Projektname und Ports kommen beide von außen – -p und die Variablen aus Drill 1.

Lösung

cd ~/compose-lab/tag01
API_PORT=8081 WEB_PORT=3001 docker compose -p notes2 up -d
docker compose ls
curl -s -X POST localhost:3001/api/notes -H 'Content-Type: application/json' \
  -d '{"text":"nur in notes2"}'; echo
curl -s localhost:8081/notes; echo
curl -s localhost:8080/notes; echo
docker compose -p notes2 down --rmi local

Erwartet (gekürzt):

 Container notes2-api-1 Started
 Container notes2-web-1 Started
 Container notes2-worker-1 Started
NAME     STATUS       CONFIG FILES
notes    running(3)   /Users/du/compose-lab/tag01/compose.yaml
notes2   running(3)   /Users/du/compose-lab/tag01/compose.yaml
{"id":"f59f49a4-…","text":"nur in notes2"}
[{"id":"f59f49a4-…","text":"nur in notes2"}]
[{"id":"4531570d-…","text":"Kontrollpunkt Tag 1"}]
 Network notes2_default Removed
 Image notes2-api:latest Removed
 Image notes2-web:latest Removed
 Image notes2-worker:latest Removed

-p schlägt name: notes, also heißen Container, Netz und Images notes2-… und kollidieren nicht. Die Ports kommen aus den Variablen, die Datei bleibt unverändert. notes2 baut eigene Images (aus dem Build-Cache, daher schnell); --rmi local entfernt sie wieder. Dein Projekt notes kennt nur die Notiz aus dem Kontrollpunkt. Dasselbe als Skript: code/tag01/challenge/zweite-instanz.sh.

Zum Schluss des Tages:

docker compose down

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Die compose.yaml gehört ins Repository neben den Code; .env nicht (nur .env.example). So startet jede Person im Team denselben Stack mit eigenen Werten.
  • Eindeutige Projektnamen (-p bzw. COMPOSE_PROJECT_NAME) sind in CI Pflicht, damit parallele Pipelines auf einem Runner sich nicht gegenseitig Container ersetzen (Tag 13).
  • Ports nur an 127.0.0.1 binden. Ein "8080:8080" ohne Adresse lauscht auf allen Schnittstellen – auf einem Server direkt im Netz, oft an der Host-Firewall vorbei.
  • docker compose config als Lint-Schritt in jeder Pipeline: fängt Tippfehler und fehlende Variablen ab, bevor etwas startet. Die Ausgabe enthält aber Klartext-Werte.
  • Speicherbetrieb wie heute ist nur für Demos gedacht. Was einen restart überleben muss, braucht ein Volume (Tag 3).