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 unterenvironment:oderenv_file:steht. .envim Projektordner dient nur der Interpolation. Die Shell schlägt.env,--env-fileersetzt.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"}'; echoErwartet (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 inspectunddocker 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 -2Erwartet (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 -dErwartet (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 -1Erwartet (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 ${…}:
- Variablen der Shell,
- sonst Dateien aus
--env-file, - ohne
--env-filedie.envim 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 -1Erwartet (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:.envwird nicht mehr gelesen, der Key fehlt – dein:?aus Drill 2 fängt das ab. - Mehrere
--env-fileliest 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 workerTipp: 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.envErgä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 INTERVALErwartet (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.envIm 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;
EOFIn 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 SkippingErwartet (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; echoErwartet (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 -1Erwartet (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 -1Erwartet (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 -1Erwartet (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; echoErwartet:
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.bakIm 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 -dErwartet (gekürzt):
Container notes-db-1 Recreated
Container notes-db-1 Started
Fortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
- In
.envgehö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 configunddocker inspectenthalten Werte im Klartext. In Pipelines nurconfig -qoderconfig --no-interpolateloggen. - 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:demenv:im Pod; das Problem „wer gewinnt“ heißt dortenvFromgegenenv.