Docker Compose Env-Praezedenz: Shell, .env, environment, env_file im Ueberblick

1. Zwei getrennte Mechanismen, ein gemeinsamer Name

Der haeufigste Denkfehler bei Docker Compose ist die Annahme, es gebe nur einen Topf mit Umgebungsvariablen. Tatsaechlich laufen zwei komplett getrennte Mechanismen parallel: die Interpolation von Platzhaltern wie ${VAR} innerhalb der compose.yaml selbst, und die Injektion von Umgebungsvariablen in den laufenden Container. Beide nutzen dieselbe Syntax und teilweise dieselben Quellen, folgen aber unterschiedlichen Regeln. Wer das nicht trennt, sucht Stunden nach einem Bug, der eigentlich ein Missverstaendnis ist.

Fuer die Interpolation liest Compose die Werte aus der Shell-Umgebung und aus einer .env-Datei im Projektverzeichnis, noch bevor die YAML-Datei ueberhaupt geparst wird. Fuer die Container-Injektion greifen zusaetzlich der environment-Block und env_file innerhalb der Service-Definition. Ein Wert kann also in der YAML-Datei interpoliert werden, ohne dass er jemals im Container ankommt, und umgekehrt kann ein Wert im Container landen, ohne dass er fuer die Interpolation sichtbar war.

2. Shell-Umgebung: die staerkste Quelle fuer Interpolation

Fuer die Interpolation von ${VAR}-Platzhaltern in der Compose-Datei hat die Shell-Umgebung, in der docker compose aufgerufen wird, die hoechste Prioritaet. Setzt man export TAG=v2 vor dem Aufruf, ueberschreibt dieser Wert automatisch jeden gleichnamigen Eintrag in der .env-Datei, egal was dort steht. Das ist beabsichtigt: CI-Pipelines und lokale Overrides sollen ohne Dateiaenderung funktionieren.

Genau das ist aber auch die haeufigste Fehlerquelle. Ein Entwickler exportiert DB_HOST in seiner .bashrc fuer ein anderes Projekt, vergisst das, und wundert sich Wochen spaeter, warum ein voellig neues Compose-Projekt eine falsche Datenbank anspricht. Der Befehl docker compose config zeigt die final aufgeloeste Konfiguration inklusive aller interpolierten Werte und ist der erste Debugging-Schritt, bevor man ueberhaupt Container startet.

# Aktive Shell-Variablen pruefen, die mit dem Projekt kollidieren koennten
env | grep -iE 'DB_|TAG|PORT'

# Final aufgeloeste Konfiguration anzeigen (nach Interpolation)
docker compose config

# Nur einen bestimmten Wert extrahieren
docker compose config | grep -A2 'DB_HOST'

3. Die .env-Datei: stiller Standardwert fuer die Interpolation

Liegt im selben Verzeichnis wie der docker compose-Aufruf eine Datei namens .env, liest Compose sie automatisch und stellt jede Zeile als Interpolationsquelle bereit, allerdings nur mit niedrigerer Prioritaet als die Shell-Umgebung. Die Syntax ist simpel: SCHLUESSEL=Wert pro Zeile, Kommentare mit #, keine Anfuehrungszeichen noetig, aber erlaubt. Wichtig: Diese Datei wird ausschliesslich von Compose selbst gelesen, nicht automatisch in den Container injiziert.

Ein zweites Missverstaendnis betrifft den Dateipfad. Compose sucht standardmaessig eine .env im aktuellen Arbeitsverzeichnis, nicht im Verzeichnis der compose.yaml, falls man diese ueber -f aus einem anderen Ordner referenziert. Seit neueren Compose-Versionen laesst sich das ueber --env-file explizit steuern, was gerade bei mehreren Umgebungen (dev, staging, prod) mit jeweils eigener Env-Datei unverzichtbar ist.

# Explizite Env-Datei fuer eine bestimmte Umgebung erzwingen
docker compose --env-file .env.staging up -d

# .env liegt woanders als die compose.yaml
docker compose -f deploy/compose.yaml --env-file deploy/.env.prod up -d

4. Der environment-Block: explizite Injektion in den Container

Der environment-Block innerhalb einer Service-Definition ist die direkteste Methode, eine Variable in den Container zu injizieren. Er kann Literalwerte enthalten oder selbst wieder interpolierte Platzhaltern wie ${DB_PASSWORD}, die dann aus Shell oder .env aufgeloest werden. Entscheidend: Werte im environment-Block ueberschreiben immer alles, was aus env_file fuer denselben Schluessel kommt, unabhaengig von der Reihenfolge im YAML-Dokument.

Eine haeufig uebersehene Variante ist die Kurzform ohne Wert, etwa nur - DB_PASSWORD ohne Gleichheitszeichen. In diesem Fall uebernimmt Compose den Wert aus der Shell-Umgebung des Host-Systems und reicht ihn unveraendert durch, was praktisch fuer Secrets ist, die nicht in einer Datei landen sollen, aber leicht vergessen wird und zu leeren Variablen im Container fuehrt, wenn die Shell den Wert gar nicht gesetzt hat.

services:
  app:
    image: myapp:latest
    environment:
      NODE_ENV: production
      DB_HOST: db
      DB_PASSWORD: ${DB_PASSWORD}   # aus Shell oder .env aufgeloest
      # Kurzform: Wert direkt aus der Host-Shell durchreichen
      - API_TOKEN

5. env_file: ganze Dateien als Variablenquelle einbinden

Waehrend der environment-Block fuer wenige, explizite Werte gedacht ist, dient env_file dem Einbinden ganzer Variablenlisten aus separaten Dateien, etwa app.env oder secrets.env. Diese Dateien werden nicht interpoliert, das heisst Platzhalter wie ${VAR} innerhalb einer per env_file geladenen Datei bleiben als Literal-String stehen und werden nicht aufgeloest, ein Unterschied, der regelmaessig zu falschen Erwartungen fuehrt.

Werden mehrere Dateien in einer Liste angegeben, gewinnt bei gleichem Schluessel die zuletzt genannte Datei. Kombiniert man env_file mit einem environment-Block, hat der environment-Block immer das letzte Wort, selbst wenn er in der YAML-Datei vor env_file steht. Diese Praezedenz ist in der Compose-Spezifikation festgelegt und nicht von der Reihenfolge der Schluessel im Dokument abhaengig.

services:
  app:
    image: myapp:latest
    env_file:
      - ./config/base.env
      - ./config/local.env   # ueberschreibt Werte aus base.env
    environment:
      # gewinnt IMMER gegenueber env_file, egal an welcher Position
      NODE_ENV: production

6. Die vollstaendige Praezedenz-Kette in der Praxis

Zusammengefasst gilt fuer die finale Variable im Container folgende Reihenfolge von hoechster zu niedrigster Prioritaet: ein im Dockerfile per ENV gesetzter Wert wird von env_file ueberschrieben, env_file wird vom environment-Block ueberschrieben, und falls die Shell beim Container-Start noch docker compose run -e VAR=wert nutzt, gewinnt dieser Wert ueber alles andere. Fuer die reine YAML-Interpolation gilt separat: Shell-Umgebung schlaegt .env-Datei.

In der Praxis lohnt sich eine feste Konvention pro Team: Secrets und geheime Werte kommen ausschliesslich per env_file aus einer nicht versionierten Datei, feste Konfigurationswerte wie Portnummern stehen direkt im environment-Block, und projektweite Defaults wie die Compose-Projektbezeichnung liegen in der .env-Datei. Diese Trennung reduziert die Zahl der Stellen, an denen ein Wert ueberschrieben werden kann, drastisch.

# Einzelnen Wert fuer einen einmaligen Lauf ueberschreiben
docker compose run -e DEBUG=true app npm test

# Effektive Umgebung eines laufenden Containers pruefen
docker compose exec app env | sort

7. Zusatzfaktor: mehrere Compose-Dateien mit -f

Wird ein Projekt mit mehreren -f-Flags gestartet, etwa docker compose -f compose.yaml -f compose.override.yaml up, gilt fuer environment-Bloecke: Die spaeter angegebene Datei ueberschreibt gleichnamige Schluessel aus der frueheren. Fuer Listen wie env_file werden die Eintraege dagegen zusammengefuehrt (gemerged), nicht ersetzt, sofern nicht explizit ein leeres Array die Liste zuruecksetzt. Diese asymmetrische Merge-Logik zwischen Skalar- und Listenfeldern ist eine der subtilsten Fallen in mehrschichtigen Compose-Setups.

Ein compose.override.yaml wird von Compose automatisch mitgeladen, wenn es im selben Verzeichnis wie die Haupt-Compose-Datei liegt, ganz ohne explizites -f. Das ist praktisch fuer lokale Entwickler-Overrides, kann aber zu Verwirrung fuehren, wenn ein Teammitglied nicht weiss, dass diese Datei existiert und automatisch greift. Ein kurzer Blick mit docker compose config deckt solche versteckten Overrides zuverlaessig auf.

8. Systematisches Debugging bei falschen Werten

Kommt ein unerwarteter Wert im Container an, hilft ein dreistufiges Vorgehen: Erstens docker compose config ausfuehren, um die nach Interpolation aufgeloeste YAML-Struktur zu sehen. Zweitens pruefen, ob eine .env-Datei oder Shell-Variable existiert, die den Platzhalter unerwartet fuellt. Drittens im laufenden Container selbst mit docker compose exec app env die tatsaechlich injizierten Variablen inspizieren, denn Interpolationsergebnis und Container-Umgebung sind zwei verschiedene Dinge.

Ein haeufiger Sonderfall ist eine leere statt einer fehlenden Variable. Wird ${VAR} interpoliert und ist VAR weder in der Shell noch in .env gesetzt, ersetzt Compose den Platzhalter standardmaessig durch einen leeren String, ohne Fehler oder Warnung. Erst mit der Syntax ${VAR:?Fehlermeldung} bricht Compose den Start kontrolliert ab, was fuer produktionskritische Variablen wie Datenbank-Zugangsdaten dringend empfohlen ist.

services:
  app:
    environment:
      # Bricht den Start mit klarer Fehlermeldung ab, falls nicht gesetzt
      DB_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD muss gesetzt sein}
      # Fallback-Wert, falls die Variable fehlt
      LOG_LEVEL: ${LOG_LEVEL:-info}

9. Empfehlungen fuer stabile Compose-Konfigurationen

Eine .env.example-Datei ohne echte Werte, dafuer aber mit allen erwarteten Schluesseln, im Repository zu versionieren, macht fuer neue Teammitglieder sofort sichtbar, welche Variablen ueberhaupt existieren. Die echte .env gehoert in die .gitignore, ebenso jede Datei, die per env_file echte Secrets enthaelt. Diese Trennung von Struktur (versioniert) und Werten (nicht versioniert) verhindert die haeufigste Ursache fuer versehentlich committete Zugangsdaten.

Fuer mehrere Umgebungen empfiehlt sich ein konsistentes Namensschema wie .env.dev, .env.staging, .env.prod, kombiniert mit dem expliziten --env-file-Flag statt sich auf implizites Auto-Loading zu verlassen. Wer zusaetzlich in der CI-Pipeline pruefen laesst, ob alle in der Compose-Datei referenzierten Variablen tatsaechlich gesetzt sind, etwa per docker compose config --quiet mit Fehlerauswertung, fängt fehlende Werte ab, bevor sie in Produktion zu leeren Strings werden.

10. Zusammenfassung

11. FAQ: Compose-Env-Praezedenz: Das Wichtigste auf einen Blick