docker compose config: Mehrere Compose-Dateien validieren und mergen

1. Das Problem mehrerer Compose-Dateien und Overrides

Sobald ein Projekt ueber eine einzelne docker-compose.yml hinausgeht und zusaetzliche Dateien fuer Entwicklung, Staging und Produktion einsetzt, etwa docker-compose.override.yml oder docker-compose.prod.yml, wird die tatsaechlich wirksame Konfiguration schnell unuebersichtlich. Jede zusaetzliche Datei kann Werte aus vorherigen Dateien ueberschreiben, ergaenzen oder in Listen anhaengen, je nach Schluessel und Datentyp, was ohne genaue Kenntnis der Merge-Regeln zu Ueberraschungen fuehrt.

Ein haeufiges Symptom ist, dass ein Service beim Start ein voellig anderes Image oder eine unerwartete Umgebungsvariable verwendet, als in der Haupt-Compose-Datei angegeben, weil eine der zusaetzlichen -f-Dateien den Wert stillschweigend ueberschrieben hat. Ohne ein Werkzeug, das die gemergte Konfiguration explizit anzeigt, bleibt oft nur muehsames manuelles Nachverfolgen der Werte durch alle beteiligten Dateien.

2. Grundlagen von docker compose config

docker compose config liest alle mit -f angegebenen Compose-Dateien in der uebergebenen Reihenfolge ein, wendet die Merge-Regeln an und gibt die vollstaendige, aufgeloeste Konfiguration als YAML auf der Standardausgabe aus, ohne dabei tatsaechlich irgendeinen Container zu starten. Das macht den Befehl zum idealen ersten Schritt jeder Fehlersuche bei unerwartetem Verhalten eines Compose-Stacks.

In der Ausgabe sind alle Variablen aus .env-Dateien bereits interpoliert, alle relativen Pfade in absolute Pfade aufgeloest und alle YAML-Anchors und -Aliase expandiert, sodass die Ausgabe exakt dem entspricht, was Docker Compose tatsaechlich an die Docker-Engine uebergeben wuerde, wenn der Stack gestartet wird.

# Gemergte Konfiguration aus mehreren Dateien anzeigen
docker compose -f docker-compose.yml -f docker-compose.override.yml config

# Konfiguration fuer die Produktionsumgebung anzeigen
docker compose -f docker-compose.yml -f docker-compose.prod.yml config

3. Merge-Reihenfolge und Override-Regeln verstehen

Die Reihenfolge der -f-Flags ist entscheidend: Jede weitere Datei wird ueber die vorherigen gelegt, spaetere Dateien gewinnen bei einfachen Skalarwerten wie image oder restart. Bei Listen wie ports oder volumes haengt das Verhalten vom konkreten Schluessel ab, manche Listen werden vollstaendig ersetzt, waehrend environment und labels als Key-Value-Strukturen zusammengefuehrt werden und einzelne Schluessel gezielt ueberschreiben, ohne die restlichen Eintraege zu verlieren.

Diese unterschiedlichen Merge-Strategien pro Schluessel sind der Kern vieler Override-Ueberraschungen: Wer erwartet, dass ports in einer Override-Datei ergaenzend zur Basisdatei wirkt, wird von der tatsaechlichen Ersetzungslogik ueberrascht, wenn ploetzlich nur noch der in der Override-Datei definierte Port aktiv ist. docker compose config macht genau diese Diskrepanz zwischen Erwartung und tatsaechlichem Verhalten sofort sichtbar.

4. Syntax-Validierung vor dem Start

Neben der reinen Anzeige der gemergten Konfiguration prueft docker compose config automatisch die Syntax aller eingebundenen Dateien und meldet Fehler wie fehlerhaftes YAML, unbekannte Top-Level-Schluessel oder ungueltige Werte fuer bekannte Felder, bevor irgendein Container gestartet wird. Das ist besonders in CI-Pipelines wertvoll, wo ein fehlerhafter Compose-Stack sonst erst beim eigentlichen Deploy-Versuch auffallen wuerde.

Die --quiet Option unterdrueckt dabei die vollstaendige YAML-Ausgabe und liefert nur den Exit-Code zurueck, was den Befehl ideal fuer automatisierte Validierungsschritte macht, die lediglich pruefen wollen, ob eine Konfiguration gueltig ist, ohne die potenziell lange Ausgabe in Logs zu schreiben oder weiterzuverarbeiten.

# Nur Syntax pruefen, keine Ausgabe der vollen Konfiguration
docker compose -f docker-compose.yml -f docker-compose.override.yml config --quiet
echo "Exit-Code: $?"

# Bei einem Syntaxfehler wird eine klare Fehlermeldung ausgegeben
docker compose -f docker-compose.yml -f docker-compose.broken.yml config

5. Ein Debugging-Beispiel mit fehlerhafter Override-Datei

Ein typisches Szenario: Ein Team fuegt eine docker-compose.override.yml hinzu, um lokal einen anderen Datenbank-Port zu nutzen, definiert dabei aber versehentlich den kompletten ports-Block neu, statt nur den einen Port zu aendern. Der Service startet zwar, aber ein zweiter, in der Basisdatei definierter Port fuer einen Debug-Endpunkt ist ploetzlich nicht mehr erreichbar, ohne dass eine Fehlermeldung darauf hinweist.

docker compose config deckt dieses Verhalten sofort auf: In der gemergten Ausgabe erscheint nur noch der eine, in der Override-Datei definierte Port, der zweite fehlt komplett. Diese Diskrepanz zwischen dem, was im Compose-File vermeintlich additiv gedacht war, und dem, was tatsaechlich gemergt wird, ist mit blossem Auge in den einzelnen Dateien kaum zu erkennen, in der aufgeloesten Ausgabe dagegen sofort offensichtlich.

6. Wie Umgebungsvariablen und .env in der Config aufgeloest werden

Werte in Compose-Dateien, die auf Umgebungsvariablen verweisen, etwa ${DATABASE_URL} oder ${TAG:-latest} mit Default-Wert, werden in der Ausgabe von docker compose config vollstaendig aufgeloest angezeigt, sodass sofort sichtbar wird, welcher tatsaechliche Wert verwendet wird, statt nur den Platzhalter im Quelltext zu sehen. Das ist besonders hilfreich, wenn mehrere .env-Dateien oder exportierte Shell-Variablen um Vorrang konkurrieren.

Fehlt eine referenzierte Variable komplett und ist kein Default-Wert angegeben, ersetzt Docker Compose den Platzhalter durch einen leeren String und gibt in aelteren Versionen oft nur eine Warnung aus, was in der Praxis zu schwer nachvollziehbaren leeren Konfigurationswerten fuehren kann. Ein Blick in die config-Ausgabe deckt genau diese leeren Werte auf, bevor sie als scheinbar gueltige, aber inhaltlich falsche Konfiguration an einen Container weitergereicht werden.

# Aufloesung von Variablen in der Config pruefen
DATABASE_URL=postgres://user:pass@db:5432/app \
  docker compose -f docker-compose.yml config | grep -A2 environment

7. Profile in der Config-Ausgabe filtern

Compose-Profile erlauben es, Services optional zu machen und nur bei Bedarf zu starten, etwa einen zusaetzlichen Debugging-Container, der im normalen Betrieb nicht laufen soll. docker compose config beruecksichtigt aktive Profile ueber das --profile Flag und zeigt nur die Services an, die mit den angegebenen Profilen tatsaechlich aktiviert wuerden, was hilft zu verstehen, welche Services in einer bestimmten Umgebung tatsaechlich gestartet werden.

Ohne explizit angegebenes Profil zeigt docker compose config standardmaessig alle Services inklusive der Profile-gebundenen an, aber mit einem Hinweis, dass sie ohne aktives Profil beim eigentlichen up-Befehl nicht gestartet werden. Dieser Unterschied zwischen 'in der Konfiguration vorhanden' und 'tatsaechlich gestartet' ist ein haeufiger Verwirrungspunkt, den ein gezielter Blick mit --profile ausraeumt.

8. Einsatz in CI zur Vorab-Validierung

In CI-Pipelines lohnt sich ein fruehzeitiger docker compose config --quiet Schritt direkt nach dem Checkout, bevor irgendein Build oder Deploy versucht wird, weil ein fehlerhaftes Compose-Setup so innerhalb von Sekunden erkannt wird, statt erst nach einem langwierigen Build-Schritt zu scheitern. Das spart insbesondere bei Monorepos mit mehreren Compose-Dateien wertvolle Pipeline-Zeit.

Ergaenzend kann die vollstaendige Config-Ausgabe als Artefakt in der Pipeline abgelegt werden, sodass bei einem spaeteren Deploy-Problem sofort nachvollziehbar ist, welche Konfiguration zum Zeitpunkt des jeweiligen Runs tatsaechlich gemergt und verwendet wurde, was bei Fehlersuchen im Nachhinein erhebliche Zeit sparen kann gegenueber dem Versuch, die Merge-Logik nachtraeglich manuell zu rekonstruieren.

# .gitlab-ci.yml Ausschnitt: Compose-Validierung als eigener Job
validate-compose:
  stage: validate
  script:
    - docker compose -f docker-compose.yml -f docker-compose.prod.yml config --quiet
    - docker compose -f docker-compose.yml -f docker-compose.prod.yml config > compose-resolved.yml
  artifacts:
    paths:
      - compose-resolved.yml

9. Praxis-Tipps fuer den taeglichen Umgang

Ein bewaehrter Griff ist, docker compose config nicht nur bei Fehlersuche, sondern routinemaessig nach jeder Aenderung an einer der beteiligten Compose-Dateien laufen zu lassen, am besten als lokaler Git-Pre-Commit-Hook oder als expliziter Schritt in der Entwickler-Dokumentation. So werden Merge-Ueberraschungen bereits vor dem Commit entdeckt, statt erst beim naechsten Deploy oder bei einem Kollegen, der dieselben Compose-Dateien mit anderer -f-Reihenfolge nutzt.

Fuer Teams mit vielen Umgebungen empfiehlt es sich zudem, fuer jede Zielumgebung ein festes Set an -f-Flags in einem Makefile oder Shell-Alias zu hinterlegen, damit die Reihenfolge nie versehentlich vertauscht wird, denn eine vertauschte Reihenfolge fuehrt zu einer komplett anderen gemergten Konfiguration, ohne dass Docker Compose selbst davor warnt.

10. Zusammenfassung

11. FAQ: docker compose config: Das Wichtigste auf einen Blick