Mehrere Compose-Dateien kombinieren - das Override-Pattern

Docker Compose kann mehrere Dateien zusammenführen — das ermöglicht saubere Trennung zwischen Basis-Konfiguration und umgebungsspezifischen Anpassungen.

Das automatische Override

Wenn im selben Verzeichnis eine docker-compose.override.yml liegt, lädt Compose sie automatisch beim up-Befehl:

docker compose up   # Lädt docker-compose.yml + docker-compose.override.yml automatisch

Das Basis-File bleibt produktionsfähig, die Override-Datei fügt lokale Anpassungen hinzu — ohne das Basis-File anzufassen.

Manuelle Dateiangabe mit -f

Für mehr Kontrolle oder abweichende Dateinamen:

docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d
docker compose -f docker-compose.yml -f docker-compose.test.yml run tests

Die Reihenfolge ist entscheidend: spätere Dateien überschreiben frühere.

Praxisbeispiel: Dev vs. Prod

docker-compose.yml (Basis, produktionstauglich):

services:
  app:
    image: myapp:${APP_VERSION}
    environment:
      APP_ENV: production
    restart: unless-stopped

  db:
    image: postgres:16
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

docker-compose.override.yml (nur lokal, nicht committen oder als Vorlage):

services:
  app:
    build: .          # Lokal aus Quellcode bauen statt Image ziehen
    environment:
      APP_ENV: development
      DEBUG: "true"
    ports:
      - "8080:8080"   # Port nur lokal exponieren
    volumes:
      - .:/app        # Hot-Reload: lokaler Code gemountet

  db:
    ports:
      - "5432:5432"   # DB lokal direkt erreichbar für Tools wie DBeaver

Merge-Verhalten verstehen

Compose führt Dateien nicht blind zusammen — es gibt klare Regeln:

Skalare werden überschrieben:

# Basis: image: myapp:1.0
# Override: image: myapp:dev
# Ergebnis: image: myapp:dev

Listen werden angehängt:

# Basis: ports: ["80:80"]
# Override: ports: ["8080:8080"]
# Ergebnis: ports: ["80:80", "8080:8080"]

Maps (environment, labels) werden gemergt:

# Basis: environment: {APP_ENV: prod}
# Override: environment: {DEBUG: true}
# Ergebnis: environment: {APP_ENV: prod, DEBUG: true}

Weitere Anwendungsfälle

Monitoring-Sidecar hinzufügen:

# docker-compose.monitoring.yml
services:
  prometheus:
    image: prom/prometheus
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    ports:
      - "9090:9090"

docker compose -f docker-compose.yml -f docker-compose.monitoring.yml up -d

Lokales SSL:

# docker-compose.ssl.yml
services:
  app:
    environment:
      HTTPS_CERT: /certs/local.crt
    volumes:
      - ./certs:/certs:ro

Tipp: Konfiguration prüfen vor dem Start

docker compose -f docker-compose.yml -f docker-compose.override.yml config

Zeigt die zusammengeführte Konfiguration — nützlich zur Fehlersuche, bevor man Container startet.

Das Override-Pattern hält Basis-Konfigurationen sauber und produkionstauglich, während lokale Entwicklungsanpassungen sauber getrennt bleiben.