Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 7: Mehrere Dateien

Ziel: Eine Anwendung auf mehrere Compose-Dateien verteilen – Override für die Entwicklung, Werkzeuge per include, Wiederverwendung mit extends, Zuschalten mit Profilen. · Dauer: ca. 60 min · Voraussetzung: Tag 6

Briefing

  • -f a.yaml -f b.yaml legt Dateien übereinander: Die spätere gewinnt, nach festen Merge-Regeln. Ohne -f lädt Compose compose.yaml und, falls vorhanden, compose.override.yaml.
  • !reset und !override entfernen oder ersetzen Werte, statt sie zu mischen.
  • include: bindet eine andere Datei als eigenes Teilprojekt ein, extends: erbt einen einzelnen Dienst.
  • profiles: markiert Dienste, die nur auf Wunsch laufen – hier die Werkzeuge psql und backup.
compose.yaml ──include──► compose.tools.yaml   (psql, backup: Profil tools)
     │
     └── -f compose.dev.yaml  (nur Entwicklung: web im Watch-Modus)

Drill 1: Aus dem Override wird compose.dev.yaml

source ~/compose-lab/setup/env.sh
docker compose -p notes down
mkdir -p ~/compose-lab/tag07 && cd ~/compose-lab/tag07
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag06/notes/." .
docker compose config --format json \
  | jq -c '.services.web | {target: .build.target, command}'

Erwartet:

{"target":"build","command":["node","--watch","server.js"]}

compose.override.yaml aus Tag 6 wird ohne Zutun geladen. Praktisch beim Entwickeln, gefährlich überall sonst: Wer auf einem Server docker compose up tippt und die Datei mitkopiert hat, startet den Dev-Modus. Ab heute heißt sie compose.dev.yaml und wirkt nur, wenn du sie nennst. jq statt der ganzen Ausgabe von config hat einen Grund: Die zeigt auch die Werte aus .env (Tag 4).

rm compose.override.yaml
cat > compose.dev.yaml <<'EOF'
# compose.dev.yaml – Entwicklung, nur per -f zusammen mit compose.yaml (Tag 7)
services:
  web:
    build:
      target: build
    command: ["node", "--watch", "server.js"]
    environment:
      NODE_ENV: development
EOF
docker compose config --format json \
  | jq -c '.services.web | {target: .build.target, command}'
docker compose -f compose.yaml -f compose.dev.yaml config --format json \
  | jq -c '.services.web | {target: .build.target, command}'

Erwartet:

{"target":null,"command":null}
{"target":"build","command":["node","--watch","server.js"]}

Sobald du ein -f angibst, lädt Compose genau diese Dateien und keine automatische Override-Datei mehr.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Merge-Regeln

Eine Wegwerf-Datei zeigt, was beim Übereinanderlegen passiert:

cat > compose.drill.yaml <<'EOF'
# compose.drill.yaml – nur für Tag 7, Drill 2 und 3
services:
  worker:
    restart: "no"
    environment:
      INTERVAL: "2"
  api:
    ports:
      - "127.0.0.1:${DRILL_PORT:-8081}:8080"
EOF
docker compose -f compose.yaml -f compose.drill.yaml config --format json \
  | jq -c '.services.worker | {restart, interval: .environment.INTERVAL,
           api_url: .environment.NOTES_API_URL}'
docker compose -f compose.yaml -f compose.drill.yaml config --format json \
  | jq -c '.services.api.ports[] | {host_ip, published, target}'

Erwartet:

{"restart":"no","interval":"2","api_url":"http://api:8080"}
{"host_ip":"127.0.0.1","published":"8080","target":8080}
{"host_ip":"127.0.0.1","published":"8081","target":8080}
Art Beispiele Ergebnis
Einzelwert image, command, restart spätere Datei ersetzt
Map environment, labels gemischt, pro Schlüssel gewinnt die spätere
Liste ports, expose, dns, tmpfs aneinandergehängt
Mounts volumes, devices gemischt über den Zielpfad im Container

restart wurde ersetzt, INTERVAL überschrieben, NOTES_API_URL blieb, und api veröffentlicht jetzt zwei Ports. Relative Pfade in allen Dateien gelten ab dem Verzeichnis der ersten Datei (Doku: „Merge Compose files”).

Fortschritt speichern? Kostenlos registrieren

Drill 3: !reset und !override

Wenn Mischen nicht reicht: !reset setzt einen Wert auf leer zurück, !override ersetzt ihn vollständig.

cat > compose.drill.yaml <<'EOF'
# compose.drill.yaml – nur für Tag 7, Drill 2 und 3
services:
  worker:
    environment:
      INTERVAL: !reset null
  api:
    ports: !override
      - "127.0.0.1:${DRILL_PORT:-8081}:8080"
  web:
    ports: !reset []
EOF
docker compose -f compose.yaml -f compose.drill.yaml config --format json \
  | jq -c '{worker_env: (.services.worker.environment | keys),
           api_ports: [.services.api.ports[].published],
           web_ports: .services.web.ports}'
rm compose.drill.yaml

Erwartet:

{"worker_env":["NOTES_API_KEY","NOTES_API_URL"],"api_ports":["8081"],"web_ports":null}

Typische Einsätze: CI ohne veröffentlichte Ports (ports: !reset [], Tag 13), ein anderer Port statt eines zusätzlichen (!override), Konfigurationsquellen tauschen (Tag 14).

Fortschritt speichern? Kostenlos registrieren

Drill 4: Entwickeln mit -f und COMPOSE_FILE

Zwei -f bei jedem Befehl sind lästig. COMPOSE_FILE nimmt die Liste auf, getrennt mit : (Windows: ;):

export COMPOSE_FILE=compose.yaml:compose.dev.yaml
docker compose up -d --build --wait
docker compose ls --filter name=notes --format json \
  | jq -r '.[].ConfigFiles' | tr , '\n'
docker compose ps web --no-trunc --format '{{.Command}}'

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

 …
 Container notes-api-1 Healthy
 Container notes-db-1 Healthy
 Container notes-web-1 Healthy
/Users/du/compose-lab/tag07/compose.yaml
/Users/du/compose-lab/tag07/compose.dev.yaml
"docker-entrypoint.sh node --watch server.js"

Watch aus Tag 6 funktioniert genauso, mit oder ohne COMPOSE_FILE. In einem zweiten Terminal:

cd ~/compose-lab/tag07
docker compose -f compose.yaml -f compose.dev.yaml watch

Ändere im ersten Terminal eine Datei unter notes-web/public/. Erwartet im zweiten (gekürzt):

 …
Watch enabled
Syncing service "web" after 1 changes were detected

Beende Watch mit Ctrl+C und mach die Änderung rückgängig. Jetzt zurück zum Normalbetrieb, nur mit compose.yaml:

unset COMPOSE_FILE
docker compose up -d --wait
docker compose ps -a web --format '{{.Service}} {{.Status}}'

Erwartet (gekürzt):

 …
container notes-web-1 is unhealthy
web Restarting (0) Less than a second ago

Die Falle: Beide Varianten bauen in dasselbe Image notes-web. Darin steckt noch die Stage build, und deren Standardbefehl ist bloß node – ohne command: aus compose.dev.yaml endet der Container sofort. Neu bauen löst es:

docker compose up -d --build --wait
docker compose ps web --no-trunc --format '{{.Command}} {{.Status}}'

Erwartet (gekürzt):

"docker-entrypoint.sh node server.js" Up 2 seconds (healthy)

Eindeutige Image-Namen mit Tag lösen das Problem grundsätzlich (Tag 8).

Fortschritt speichern? Kostenlos registrieren

Drill 5: Werkzeuge per include

Ein psql ohne Installation auf dem Mac: ein Dienst aus dem Postgres-Image, der nur den Client startet. Er bekommt eine eigene Datei:

cat > compose.tools.yaml <<'EOF'
# compose.tools.yaml – Werkzeuge (Tag 7), per include eingebunden
services:
  psql:
    image: postgres:18.6-alpine
    profiles: [tools]
    entrypoint: ["psql"]
    environment:
      PGHOST: db
      PGUSER: notes
      PGDATABASE: notes
      PGPASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD fehlt (.env)}
    networks: [backend]
    depends_on:
      db:
        condition: service_healthy
networks:
  backend:
    internal: true
EOF

Oben in compose.yaml, direkt nach name:, kommt der Verweis:

# compose.yaml – Stand Ende Tag 7
name: notes

include:
  - compose.tools.yaml

services:
  # … unverändert
docker compose config -q; echo "Exit: $?"
docker compose config --services | sort | tr '\n' ' '; echo

Erwartet:

Exit: 0
api db migrate web worker

include lädt die Datei als eigenes Teilprojekt: Relative Pfade und .env gelten ab ihrem eigenen Verzeichnis (anders als bei -f), danach landen ihre Dienste im selben Projekt notes. Deshalb darf psql von db abhängen. Das Netz backend deklariert die Datei selbst – identisch, damit sie auch allein lesbar bleibt. psql fehlt in der Liste: Es hat ein Profil (Drill 6).

Achtung: Laut Doku meldet Compose einen Fehler, wenn eine eingebundene Datei eine Ressource definiert, die es im einbindenden Projekt schon gibt. Compose 5.6.0 hat im Test stattdessen still gemischt: Ein db mit anderem image: in compose.tools.yaml wurde ohne Meldung übergangen, seine labels aber übernommen. Halte doppelte Definitionen deshalb identisch und prüf das Ergebnis mit config.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Profile

docker compose --profile tools config --services | sort | tr '\n' ' '; echo
COMPOSE_PROFILES=tools docker compose config --services | sort | tr '\n' ' '; echo
curl -s -X POST localhost:8080/notes -H 'X-API-Key: lab-api-key-123' \
  -H 'Content-Type: application/json' -d '{"text":"Tag 7 mehrere Dateien"}'; echo
docker compose run --rm psql -c 'SELECT count(*) FROM notes'

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

api db migrate psql web worker
api db migrate psql web worker
{"id":"64013bfc-…","text":"Tag 7 mehrere Dateien"}
 Container notes-db-1 Running
 …
 count
-------
     1
(1 row)

Ein Dienst mit Profil existiert nur, wenn sein Profil aktiv ist – oder wenn du ihn ausdrücklich nennst: run psql braucht kein --profile und startet db gleich mit, falls nötig. Was passiert mit up und aktivem Profil?

docker compose --profile tools up -d --wait; echo "Exit: $?"
docker compose --profile tools ps -a psql --format '{{.Name}} {{.Status}}'
docker compose --profile tools rm -f psql

Erwartet (gekürzt):

 …
container notes-psql-1 exited (0)
Exit: 1
notes-psql-1 Exited (0) 1 second ago
 …
 Container notes-psql-1 Removed

up startet psql ohne Terminal; der Client liest ein leeres stdin und endet sofort. --wait wertet das als Fehler. Werkzeuge ruft man mit run --rm auf, Profile für Dauerläufer (Prometheus und Grafana, Tag 12) aktiviert man mit --profile.

Fortschritt speichern? Kostenlos registrieren

Drill 7: extends für backup

Ein Backup braucht dieselben Variablen, dasselbe Netz und dieselbe Abhängigkeit wie psql, nur einen anderen Befehl. extends erbt den Dienst; ergänze in compose.tools.yaml unter services: nach psql:

  backup:
    extends: psql
    entrypoint: ["sh", "-c", "pg_dump --clean --if-exists > /backup/notes.sql"]
    volumes:
      - ./backup:/backup
docker compose config -q; echo "Exit: $?"
docker compose --profile tools config --format json | jq -c '.services.backup.profiles'
docker compose --profile tools config --format json | jq -c '.services.backup.networks'
docker compose run --rm backup
grep -E '^(DROP|CREATE) TABLE' backup/notes.sql

Erwartet (gekürzt):

Exit: 0
["tools"]
{"backend":null}
 …
DROP TABLE IF EXISTS public.notes;
CREATE TABLE public.notes (

backup erbt alles von psql, auch das Profil, und ersetzt nur entrypoint; die Merge-Regeln sind dieselben wie bei -f. --clean --if-exists macht den Dump direkt wieder einspielbar. Der Ordner backup/ steht seit Tag 3 in .gitignore. extends geht auch über Dateigrenzen: extends: { file: compose.tools.yaml, service: psql } – das ist die Challenge.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Kein compose.override.yaml mehr:

cd ~/compose-lab/tag07
ls compose*.yaml

Erwartet:

compose.dev.yaml
compose.tools.yaml
compose.yaml

Die Dev-Kombination ist gültig:

docker compose -f compose.yaml -f compose.dev.yaml config -q; echo "Exit: $?"

Erwartet:

Exit: 0

Ohne -f ist das Dev-Target nicht aktiv:

docker compose config --format json | jq '.services.web.build.target'

Erwartet:

null

psql und backup gibt es nur im Profil tools:

docker compose config --services
docker compose --profile tools config --services

Erwartet:

db
migrate
api
worker
web
db
migrate
psql
api
web
worker
backup

psql antwortet, das Backup entsteht:

docker compose run --rm psql -tAc 'SELECT count(*) FROM notes'
docker compose run --rm backup
grep -c 'CREATE TABLE public.notes' backup/notes.sql

Erwartet (gekürzt, Zahl kann abweichen):

 Container notes-db-1 Healthy
0
 Container notes-db-1 Healthy
1

Challenge

Schreib eine Datei compose.restore.yaml mit einem Dienst restore, der per extends aus compose.tools.yaml erbt und backup/notes.sql zurückspielt. Lösch alle Notizen, stell sie wieder her und prüf das Ergebnis über das API. Was passiert, wenn du compose.restore.yaml allein benutzt?

Hinweis: extends mit file: übernimmt den Dienst, aber nicht das Netz und nicht den Dienst db, von denen er abhängt.

Lösung

cat > compose.restore.yaml <<'EOF'
# compose.restore.yaml – Challenge Tag 7: Restore aus backup/notes.sql
services:
  restore:
    extends:
      file: compose.tools.yaml
      service: psql
    entrypoint: ["psql", "-v", "ON_ERROR_STOP=1", "-q", "-o", "/dev/null"]
    command: ["-f", "/backup/notes.sql"]
    volumes:
      - ./backup:/backup:ro
EOF
docker compose run --rm psql -c 'DELETE FROM notes' 2>/dev/null
curl -s localhost:8080/notes; echo
docker compose -f compose.yaml -f compose.restore.yaml run --rm restore 2>/dev/null
echo "Exit: $?"
curl -s localhost:8080/notes; echo
docker compose -f compose.restore.yaml run --rm restore

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

DELETE 1
[]
Exit: 0
[{"id":"64013bfc-…","text":"Tag 7 mehrere Dateien"}]
no such service: db

Zusammen mit compose.yaml findet restore Netz und db, allein nicht: extends holt nur die Dienstdefinition, keine Ressourcen, auf die sie verweist (Doku: „extends – Restrictions”). ON_ERROR_STOP=1 sorgt dafür, dass ein Fehler im Dump zu Exit-Code ungleich 0 führt; -o /dev/null schluckt die Ausgaben der SELECT-Zeilen aus dem Dump. Die Datei liegt im Begleitcode unter code/tag07/challenge/. Zum Schluss:

rm compose.restore.yaml
docker compose down

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Eine Basisdatei plus wenige, klar benannte Zusatzdateien (compose.dev.yaml, compose.ci.yaml, compose.prod.yaml) sind leichter zu prüfen als ein automatisches compose.override.yaml, das auf jedem Rechner anders aussieht.
  • Im Review zählt das Ergebnis, nicht die Einzeldatei: docker compose -f … -f … config (ohne Secrets in der Ausgabe, z. B. über jq) gehört in die Pipeline.
  • include eignet sich für gemeinsam gepflegte Bausteine (Datenbank, Observability) aus einem anderen Repository oder Ordner; jedes Team behält seine eigene .env.
  • Werkzeugdienste wie psql und backup ersetzen Wiki-Anleitungen mit langen docker run-Zeilen. In regulierten Umgebungen ersetzen sie aber kein geprüftes Backup-Verfahren mit Verschlüsselung, Aufbewahrung und Restore-Test.
  • Profile sind kein Rechtekonzept: Wer die Datei hat, kann jedes Profil starten.