Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 4: Konfiguration

Ziel: Wissen, woher jeder Wert in Compose und im Container kommt, Pflichtwerte erzwingen und Postgres beim ersten Start per configs: ein Init-Skript mitgeben. · Dauer: ca. 60 min · Voraussetzung: Tag 3

Briefing

  • Zwei Ebenen: Compose setzt ${VAR} beim Lesen der Datei ein (Interpolation). In den Container kommt nur, was unter environment: oder env_file: steht.
  • .env im Projektordner dient nur der Interpolation. Die Shell schlägt .env, --env-file ersetzt .env.
  • ${VAR:-standard} liefert einen Standardwert, ${VAR:?meldung} bricht ab, wenn der Wert fehlt oder leer ist. $$ ist ein Dollar für den Container.
  • configs: legen Dateien in den Container – aus einer Datei (file:) oder direkt aus der Compose-Datei (content:).
 Shell-Variablen ─┐                         ┌─ environment: ─┐
 --env-file / .env┴─► ${…} in compose.yaml ─┤                ├─► Container
                         (Interpolation)    └─ env_file: ────┘
 db/init/10-readonly.sql ── configs: ──► /docker-entrypoint-initdb.d/

Drill 1: .env ist für Compose, nicht für Container

Tagesstart mit dem Stand von Tag 3. Heute beginnst du mit einer leeren Datenbank (-v), denn in Drill 7 soll ein Init-Skript laufen. Dein Backup von gestern liegt in ~/compose-lab/tag03/backup.

source ~/compose-lab/setup/env.sh
docker compose -p notes down -v
mkdir -p ~/compose-lab/tag04 && cd ~/compose-lab/tag04
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag03/notes/." .
docker compose up -d db
until docker compose exec db pg_isready -h 127.0.0.1 -U notes -d notes >/dev/null; do
  sleep 1
done
docker compose run --rm api migrate
docker compose up -d
sleep 3
curl -s -X POST localhost:8080/notes -H 'X-API-Key: lab-api-key-123' \
  -H 'Content-Type: application/json' -d '{"text":"Tag 4 startet mit Daten"}'; echo

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

 Container notes-db-1 Started
time=… level=INFO msg="migration complete" table=notes
 Container notes-worker-1 Started
{"id":"8fdb2620-…","text":"Tag 4 startet mit Daten"}

Was steht in .env, und was davon sieht ein Container?

grep -v '^#' .env
docker compose exec worker printenv NOTES_API_KEY NOTES_API_URL
docker compose exec worker printenv POSTGRES_PASSWORD; echo "Exit: $?"
docker compose exec db printenv POSTGRES_PASSWORD NOTES_API_KEY; echo "Exit: $?"

Erwartet:

NOTES_API_KEY=lab-api-key-123
POSTGRES_PASSWORD=lab-db-pw-123
lab-api-key-123
http://api:8080
Exit: 1
lab-db-pw-123
Exit: 1

worker kennt den Key, weil environment: ihn per ${NOTES_API_KEY} übernimmt – nicht das Passwort. db kennt das Passwort, nicht den Key. .env selbst landet in keinem Container.

Sicherheit: Was in environment: steht, liest jeder mit Zugriff auf Docker: docker compose exec … printenv, docker inspect und docker compose config, das die Datei mit allen eingesetzten Werten ausgibt. Solche Ausgaben gehören nicht in Tickets oder CI-Logs. Tag 10 ersetzt die Variablen durch Secrets.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Standardwerte und Pflichtvariablen

Erst das Problem: Eine leere Variable in der Shell schlägt .env, und Compose setzt ohne Warnung einen leeren String ein.

NOTES_API_KEY= docker compose up -d worker
sleep 3
docker compose ps -a --format '{{.Service}}\t{{.Status}}'
docker compose logs --no-log-prefix worker api | tail -2

Erwartet (gekürzt, Zeiten weichen ab):

 Container notes-api-1 Recreated
 Container notes-worker-1 Recreated
 Container notes-api-1 Started
 Container notes-worker-1 Started
api Exited (1) 3 seconds ago
db  Up 40 seconds
web Up 38 seconds
worker  Exited (1) 2 seconds ago
time=… level=ERROR msg="start abgebrochen" err="NOTES_API_KEY oder NOTES_API_KEY_FILE
fehlt"
NOTES_API_KEY oder NOTES_API_KEY_FILE fehlt

api und worker sind abgestürzt; der Fehler fällt erst zur Laufzeit auf. Besser bricht Compose vorher ab. Die neue Datei setzt überall :? und macht das Worker-Intervall einstellbar:

cat > compose.yaml <<'EOF'
# compose.yaml – Tag 4 (Drill 2; configs folgen in Drill 6)
name: notes

services:
  api:
    build: notes-api
    environment:
      NOTES_API_KEY: ${NOTES_API_KEY:?NOTES_API_KEY fehlt (.env)}
      NOTES_DB_URL: "postgres://notes:\
        ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD fehlt (.env)}@db:5432/notes"
    ports:
      - "127.0.0.1:${API_PORT:-8080}:8080"
    networks: [frontend, backend]
    depends_on:
      - db

  worker:
    build: notes-worker
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY:?NOTES_API_KEY fehlt (.env)}
      INTERVAL: ${WORKER_INTERVAL:-10}
    depends_on:
      - api
    networks: [backend]

  web:
    build: notes-web
    environment:
      NOTES_API_URL: http://api:8080
      NOTES_API_KEY: ${NOTES_API_KEY:?NOTES_API_KEY fehlt (.env)}
    ports:
      - "127.0.0.1:${WEB_PORT:-3000}:3000"
    depends_on:
      - api
    networks: [frontend]

  db:
    image: postgres:18.6-alpine
    environment:
      POSTGRES_USER: notes
      POSTGRES_DB: notes
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD fehlt (.env)}
    volumes:
      - pgdata:/var/lib/postgresql
    networks: [backend]

networks:
  frontend: {}
  backend:
    internal: true

volumes:
  pgdata: {}
EOF
NOTES_API_KEY= docker compose up -d worker
docker compose up -d

Erwartet (gekürzt):

error while interpolating services.api.environment.NOTES_API_KEY: required variable
NOTES_API_KEY is missing a value: NOTES_API_KEY fehlt (.env)
…
 Container notes-api-1 Recreated
 Container notes-worker-1 Recreated
 Container notes-api-1 Started
 Container notes-worker-1 Started

Mit leerem Key startet nichts, die Meldung nennt Dienst, Variable und deinen Hinweis. Der zweite Aufruf nimmt wieder .env und erzeugt nur api und worker neu – web und db haben sich nicht geändert. Die DB-URL ist ein YAML-String in doppelten Anführungszeichen: \ am Zeilenende verbindet die Zeilen ohne Leerzeichen, Compose interpoliert danach.

Ausdruck Variable fehlt Variable leer
${VAR:-std} std std
${VAR-std} std leer
${VAR:?text} Abbruch mit text Abbruch mit text
${VAR?text} Abbruch mit text leer

Jetzt der Standardwert:

WORKER_INTERVAL=3 docker compose up -d worker
sleep 7
docker compose logs --no-log-prefix --since 10s worker
WORKER_INTERVAL= docker compose up -d worker
docker compose logs --no-log-prefix worker | grep started | tail -1

Erwartet (gekürzt):

 Container notes-worker-1 Recreated
worker started, api=http://api:8080, interval=3s
summary: 1 notes, 5 words
summary: 1 notes, 5 words
summary: 1 notes, 5 words
 Container notes-worker-1 Recreated
worker started, api=http://api:8080, interval=10s

Mit :- greift der Standardwert auch bei leerer Variable. ${WORKER_INTERVAL-10} hätte einen leeren String geliefert, und der Worker wäre an int("") gescheitert.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Wer gewinnt beim Interpolieren?

Laut Compose-Doku gilt beim Einsetzen von ${…}:

  1. Variablen der Shell,
  2. sonst Dateien aus --env-file,
  3. ohne --env-file die .env im Projektordner (--project-directory, sonst Ordner der ersten -f-Datei, sonst das aktuelle Verzeichnis).
echo 'WORKER_INTERVAL=5' > interval.env
docker compose --env-file interval.env up -d worker
docker compose --env-file .env --env-file interval.env up -d worker
docker compose logs --no-log-prefix worker | grep started | tail -1
WORKER_INTERVAL=7 docker compose --env-file .env --env-file interval.env up -d worker
docker compose logs --no-log-prefix worker | grep started | tail -1

Erwartet (gekürzt):

error while interpolating services.api.environment.NOTES_API_KEY: required variable
NOTES_API_KEY is missing a value: NOTES_API_KEY fehlt (.env)
…
 Container notes-worker-1 Recreated
worker started, api=http://api:8080, interval=5s
 Container notes-worker-1 Recreated
worker started, api=http://api:8080, interval=7s
  • Nur --env-file interval.env: .env wird nicht mehr gelesen, der Key fehlt – dein :? aus Drill 2 fängt das ab.
  • Mehrere --env-file liest Compose der Reihe nach, spätere überschreiben frühere.
  • Die Shell schlägt jede Datei. In CI ist das praktisch: Werte kommen als Umgebungsvariablen aus dem Secret-Store der Pipeline.

Aufräumen:

rm interval.env
docker compose up -d worker

Tipp: Welche Variablen Compose zum Interpolieren verwendet, zeigt docker compose config --environment. Die Ausgabe enthält auch die Werte aus .env.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Wer gewinnt im Container?

Für die Umgebung im Container nennt die Doku diese Reihenfolge (oben gewinnt):

Rang Quelle Beispiel
1 docker compose run -e run -e INTERVAL=1
2 environment:/env_file: mit interpoliertem Wert INTERVAL: ${WORKER_INTERVAL:-10}
3 environment: mit festem Wert NOTES_API_URL: http://api:8080
4 env_file: INTERVAL=2 in worker.env
5 ENV im Image ENV PATH=… im Dockerfile

Zum Ausprobieren bekommt worker vorübergehend eine env_file::

printf 'INTERVAL=2\nNOTES_HINT=aus worker.env\n' > worker.env

Ergänze im Dienst worker direkt unter build: notes-worker die Zeile env_file: worker.env. Dann:

docker compose run --rm --no-deps --entrypoint printenv worker INTERVAL NOTES_HINT
docker compose run --rm --no-deps -e INTERVAL=1 --entrypoint printenv worker INTERVAL
WORKER_INTERVAL=4 docker compose run --rm --no-deps --entrypoint printenv \
  worker INTERVAL

Erwartet (gekürzt, ohne die Zeilen Container … Created):

10
aus worker.env
1
4

environment: schlägt env_file: (10 statt 2), was nur in worker.env steht, kommt trotzdem an. run -e schlägt alles. --entrypoint printenv ersetzt das ENTRYPOINT ["notes-worker"] des Images, --no-deps startet api nicht mit.

Zurückbauen: Zeile env_file: worker.env wieder löschen, dann

rm worker.env

Im Endstand gibt es kein env_file:: Eine zweite Quelle für dieselben Variablen macht die Fehlersuche nur schwerer.

Fortschritt speichern? Kostenlos registrieren

Drill 5: $$ – ein Dollar für den Container

Ein Mini-Projekt mit nur einem Dienst zeigt, wer welches $ ersetzt:

mkdir -p dollar && cd dollar
cat > compose.yaml <<'EOF'
# dollar/compose.yaml – Tag 4, Drill 5: wer ersetzt das Dollarzeichen?
name: notes-dollar

services:
  hallo:
    image: alpine:3.24
    command: ["sh", "-c", "echo Compose: $HOME / Container: $$HOME"]
EOF
docker compose run --rm hallo
docker compose down
cd ..

Erwartet (gekürzt, IDs weichen ab):

 Network notes-dollar_default Created
 Container notes-dollar-hallo-run-c83f47aef9a8 Created
Compose: /Users/du / Container: /root
 Network notes-dollar_default Removed

$HOME hat Compose beim Lesen durch dein Home auf dem Mac ersetzt. Aus $$HOME wurde $HOME, und erst die Shell im Container hat es eingesetzt. Das brauchst du für Healthchecks mit CMD-SHELL (Tag 5) und für Wrapper-Skripte (Tag 10).

Fortschritt speichern? Kostenlos registrieren

Drill 6: configs – ein Init-Skript für Postgres

Das Postgres-Image führt beim ersten Start alle *.sql und *.sh aus /docker-entrypoint-initdb.d/ aus. Das Skript legt eine Leserolle an:

mkdir -p db/init
cat > db/init/10-readonly.sql <<'EOF'
-- Läuft nur beim ersten Start mit leerem Volume (docker-entrypoint-initdb.d)
CREATE ROLE notes_ro NOLOGIN;
GRANT pg_read_all_data TO notes_ro;
EOF

In compose.yaml bekommt db die Config, und am Dateiende kommt ein Top-Level-Block dazu (ganze Datei: code/tag04/notes/compose.yaml):

  db:
    image: postgres:18.6-alpine
    environment:
      POSTGRES_USER: notes
      POSTGRES_DB: notes
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD fehlt (.env)}
    volumes:
      - pgdata:/var/lib/postgresql
    configs:
      - source: db_init
        target: /docker-entrypoint-initdb.d/10-readonly.sql
    networks: [backend]
# …
configs:
  db_init:
    file: ./db/init/10-readonly.sql

Ändere auch die erste Zeile in # compose.yaml – Stand Ende Tag 4. Dann:

docker compose config -q; echo "Exit: $?"
docker compose up -d
docker compose exec db ls -l /docker-entrypoint-initdb.d
docker compose exec db psql -U notes -d notes -c '\du'
docker compose logs --no-log-prefix db | grep Skipping

Erwartet (gekürzt):

Exit: 0
 Container notes-db-1 Recreated
 Container notes-db-1 Started
total 4
-rw-r--r--    1 root     root           145 Oct 29 20:50 10-readonly.sql
                             List of roles
 Role name |                         Attributes
-----------+------------------------------------------------------------
 notes     | Superuser, Create role, Create DB, Replication, Bypass RLS

PostgreSQL Database directory appears to contain a database; Skipping initialization

Die Datei ist da, die Rolle nicht: Das Volume enthält schon eine Datenbank, also überspringt das Image die Initialisierung samt Init-Skripten. Eine file:-Config ist technisch ein Bind-Mount, deshalb gelten die Rechte vom Mac (644).

Fortschritt speichern? Kostenlos registrieren

Drill 7: Init-Skript auf leerem Volume

Damit das Skript läuft, braucht Postgres ein leeres Volume. Mit Backup davor und Restore danach geht dabei nichts verloren (Tag 3):

mkdir -p backup
docker compose exec -T db pg_dump -U notes notes > backup/notes.sql
docker compose down -v
docker compose up -d db
until docker compose exec db pg_isready -h 127.0.0.1 -U notes -d notes >/dev/null; do
  sleep 1
done
docker compose logs --no-log-prefix db | grep -E 'initdb.d|CREATE ROLE|GRANT'
docker compose exec db psql -U notes -d notes -c '\du notes_ro'
docker compose exec -T db psql -q -U notes -d notes -v ON_ERROR_STOP=1 \
  < backup/notes.sql >/dev/null
docker compose up -d
sleep 3
curl -s localhost:8080/notes; echo

Erwartet (gekürzt):

 Volume notes_pgdata Removed
 Container notes-db-1 Started
/usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/10-readonly.sql
CREATE ROLE
GRANT ROLE
      List of roles
 Role name |  Attributes
-----------+--------------
 notes_ro  | Cannot login

 Container notes-worker-1 Started
[{"id":"8fdb2620-…","text":"Tag 4 startet mit Daten"}]

Rolle angelegt, Notiz zurück. Init-Skripte sind für die Erstinitialisierung gedacht: Was später dazukommt, gehört in eine Migration (Tag 5) oder wird von Hand nachgezogen.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Alle Variablen sind gesetzt; up --dry-run liest und interpoliert die Datei wie ein echtes up, ändert aber nichts:

cd ~/compose-lab/tag04
docker compose up --dry-run >/dev/null; echo "Exit: $?"

Erwartet:

Exit: 0

Ein leerer Key bricht mit Meldung ab:

NOTES_API_KEY='' docker compose up --dry-run 2>&1 | tail -1

Erwartet (gekürzt):

error while interpolating services.worker.environment.NOTES_API_KEY: required variable
NOTES_API_KEY is missing a value: NOTES_API_KEY fehlt …

Ein leeres Passwort genauso:

POSTGRES_PASSWORD='' docker compose up --dry-run 2>&1 | tail -1

Erwartet (gekürzt):

error while interpolating services.db.environment.POSTGRES_PASSWORD: required variable
POSTGRES_PASSWORD is missing a value: POSTGRES_PASSWORD fehlt …

worker läuft mit dem Standard-Intervall:

docker compose logs worker | grep 'worker started' | tail -1

Erwartet (gekürzt):

worker-1  | worker started, api=http://api:8080, interval=10s

Die .env landet nicht pauschal im Container:

docker compose exec worker printenv POSTGRES_PASSWORD; echo "Exit: $?"

Erwartet:

Exit: 1

Init-Skript eingebunden, Rolle angelegt:

docker compose exec db ls /docker-entrypoint-initdb.d
docker compose exec db psql -U notes -d notes -tAc \
  "SELECT rolname FROM pg_roles WHERE rolname = 'notes_ro'"

Erwartet:

10-readonly.sql
notes_ro

api ist gesund:

curl -s localhost:8080/healthz; echo

Erwartet:

ok

Challenge

Gib Postgres ein zweites Init-Skript 20-comment.sql, diesmal ohne eigene Datei direkt in compose.yaml. Es soll die Datenbank mit Projekt <Projektname>, Tag 4 kommentieren – den Projektnamen setzt Compose ein. Danach müssen Rolle, Kommentar und deine Notiz da sein.

Hinweis: Top-Level-configs: kennt neben file: auch content:, und Compose stellt ${COMPOSE_PROJECT_NAME} zum Interpolieren bereit; das Skript läuft nur auf leerem Volume.

Lösung

cp compose.yaml compose.yaml.bak

Im Dienst db eine zweite Config und am Ende die Quelle ergänzen (ganze Datei: code/tag04/challenge/compose.yaml):

    configs:
      - source: db_init
        target: /docker-entrypoint-initdb.d/10-readonly.sql
      - source: db_comment
        target: /docker-entrypoint-initdb.d/20-comment.sql
# …
configs:
  db_init:
    file: ./db/init/10-readonly.sql
  db_comment:
    content: |
      COMMENT ON DATABASE notes IS 'Projekt ${COMPOSE_PROJECT_NAME}, Tag 4';
docker compose exec -T db pg_dump -U notes notes > backup/notes.sql
docker compose down -v
docker compose up -d db
until docker compose exec db pg_isready -h 127.0.0.1 -U notes -d notes >/dev/null; do
  sleep 1
done
docker compose exec -T db psql -q -U notes -d notes -v ON_ERROR_STOP=1 \
  < backup/notes.sql >/dev/null
docker compose up -d
docker compose logs --no-log-prefix db | grep 'initdb.d/'
docker compose exec db ls -l /docker-entrypoint-initdb.d
docker compose exec db psql -U notes -d notes -tAc "SELECT shobj_description(oid, \
  'pg_database') FROM pg_database WHERE datname = 'notes'"
docker compose exec db psql -U notes -d notes -tAc 'SELECT count(*) FROM notes'

Erwartet (gekürzt):

 Volume notes_pgdata Removed
 Container notes-db-1 Started
 Container notes-web-1 Started
/usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/10-readonly.sql
/usr/local/bin/docker-entrypoint.sh: running /docker-entrypoint-initdb.d/20-comment.sql
total 8
-rw-r--r--    1 root     root           145 Oct 29 20:50 10-readonly.sql
-r--r--r--    1 root     root            54 Oct 29 20:51 20-comment.sql
Projekt notes, Tag 4
1

Die Skripte laufen in alphabetischer Reihenfolge. Die content:-Config legt Compose als Datei mit dem Standardmodus 0444 an, die file:-Config behält die Rechte vom Mac. Zurück zum Stand des Tages – Kommentar und Rolle bleiben in der Datenbank, den Stack räumt morgen der Tagesstart ab:

mv compose.yaml.bak compose.yaml
docker compose up -d

Erwartet (gekürzt):

 Container notes-db-1 Recreated
 Container notes-db-1 Started

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • In .env gehören nur Lab- und Entwicklungswerte. Im Repository liegt .env.example; echte Werte kommen in CI als Umgebungsvariablen aus dem Secret-Store und schlagen damit jede Datei.
  • Pro Umgebung eine eigene Datei per --env-file (dev, stage) oder eigene Compose-Dateien (Tag 7). Pflichtwerte mit :? machen fehlende Konfiguration zu einem Fehler vor dem Start statt zu einem Absturz danach.
  • Ausgaben von docker compose config und docker inspect enthalten Werte im Klartext. In Pipelines nur config -q oder config --no-interpolate loggen.
  • Init-Skripte laufen genau einmal. Schema- und Rechteänderungen danach gehören in versionierte Migrationen (Flyway, Liquibase, golang-migrate) oder in IaC für die Datenbank, nicht in neue Init-Skripte.
  • In Kubernetes entsprechen configs: einer ConfigMap als Datei, environment: dem env: im Pod; das Problem „wer gewinnt“ heißt dort envFrom gegen env.