YAML für Docker Compose: Konfigurationsmuster und Tipps

Docker Compose verwendet YAML zur Definition von Multi-Container-Anwendungen. Eine gut strukturierte docker-compose.yml ist der Unterschied zwischen einer reibungslosen Entwicklungsumgebung und stundenlangem Debuggen von Container-Problemen. Dieser Leitfaden behandelt wesentliche Muster und häufige Fallstricke.

Grundstruktur

services:
  web:
    image: nginx:alpine
    ports:
      - "80:80"
    volumes:
      - ./html:/usr/share/nginx/html
    depends_on:
      - api

  api:
    build: ./api
    ports:
      - "3000:3000"
    environment:
      DATABASE_URL: postgres://db:5432/myapp
    depends_on:
      - db

  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: myapp
      POSTGRES_PASSWORD: secret

volumes:
  pgdata:

Umgebungsvariablen

Inline

services:
  api:
    environment:
      NODE_ENV: production
      PORT: "3000"
      DEBUG: "false"

Aus Datei

services:
  api:
    env_file:
      - .env
      - .env.local  # Überschreibt .env-Werte

Variablensubstitution

Host-Umgebungsvariablen referenzieren:

services:
  api:
    image: myapp:${TAG:-latest}  # Standard ist "latest"
    environment:
      API_KEY: ${API_KEY}  # Erforderlich - schlägt fehl, wenn nicht gesetzt
      LOG_LEVEL: ${LOG_LEVEL:-info}  # Standard ist "info"

Netzwerk

Benutzerdefinierte Netzwerke

services:
  web:
    networks:
      - frontend
  api:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend

networks:
  frontend:
  backend:
    internal: true  # Kein externer Zugriff

Services im gleichen Netzwerk können sich gegenseitig über den Servicenamen erreichen. Der db-Service ist nur von api aus erreichbar, nicht von web.

Port-Mapping

ports:
  - "8080:80"         # host:container
  - "443:443"
  - "127.0.0.1:3000:3000"  # Nur an localhost binden
  - "3000"            # Zufälliger Host-Port

Volumes

Benannte Volumes (persistent)

services:
  db:
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:
    driver: local

Bind Mounts (Entwicklung)

services:
  api:
    volumes:
      - ./src:/app/src          # Quellcode
      - /app/node_modules       # Anonymes Volume (Überschreiben verhindern)

Das anonyme Volume-Muster (/app/node_modules) verhindert, dass der Host-Bind-Mount die im Container installierten Abhängigkeiten überschreibt.

Health Checks

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 30s

  api:
    depends_on:
      db:
        condition: service_healthy

Dies stellt sicher, dass api erst startet, nachdem db die Health Checks besteht — nicht nur wenn der Container startet.

Erweiterungsfelder (DRY-Muster)

Verwenden Sie x--präfixierte Felder mit YAML-Anchors, um Wiederholungen zu reduzieren:

x-common: &common
  restart: unless-stopped
  logging:
    driver: json-file
    options:
      max-size: "10m"
      max-file: "3"

x-env: &common-env
  TZ: UTC
  LOG_FORMAT: json

services:
  api:
    <<: *common
    build: ./api
    environment:
      <<: *common-env
      PORT: "3000"

  worker:
    <<: *common
    build: ./worker
    environment:
      <<: *common-env
      QUEUE: default

Mehr über YAML-Anchors erfahren Sie in unserem YAML Anchors und Aliases Leitfaden.

Multi-Stage Compose

Entwicklung vs. Produktion

# docker-compose.yml (Basis)
services:
  api:
    build: ./api
    environment:
      DATABASE_URL: postgres://db:5432/myapp

# docker-compose.override.yml (Dev - automatisch geladen)
services:
  api:
    volumes:
      - ./api/src:/app/src
    environment:
      NODE_ENV: development
      DEBUG: "true"
    ports:
      - "3000:3000"
      - "9229:9229"  # Debug-Port

# docker-compose.prod.yml
services:
  api:
    environment:
      NODE_ENV: production
    deploy:
      replicas: 3

# Entwicklung (lädt Override automatisch)
docker compose up

# Produktion
docker compose -f docker-compose.yml -f docker-compose.prod.yml up

Häufige Fallstricke

1. Nicht-quotierte Portnummern

# RISKANT - YAML interpretiert 80:80 als Basis-60-Zahl
ports:
  - 80:80

# SICHER - immer quoten
ports:
  - "80:80"

2. Boolesche Umgebungsvariablen

# FALSCH - YAML konvertiert zu Boolean
environment:
  DEBUG: true  # Wird zu Python True, nicht zum String "true"

# RICHTIG - alle Env-Werte quoten
environment:
  DEBUG: "true"

3. depends_on Timing

depends_on wartet nur auf den Container-Start, nicht auf Bereitschaft:

# Container startet, aber DB ist möglicherweise nicht bereit
depends_on:
  - db

# Auf Health Check warten
depends_on:
  db:
    condition: service_healthy

Validieren Sie Ihre Docker-Compose-Dateien mit unserem YAML Validator.

FAQ

Was ist der Unterschied zwischen `docker-compose.yml` und `compose.yml`?

Beide Dateinamen funktionieren. compose.yml ist die neuere, von Docker empfohlene Konvention. docker-compose.yml ist der Legacy-Name. Docker Compose v2+ sucht nach beiden und bevorzugt compose.yml, wenn beide existieren. Für neue Projekte verwenden Sie compose.yml.

Sollte ich Docker Compose in der Produktion verwenden?

Docker Compose eignet sich hervorragend für Entwicklung und einfache Deployments. Für Produktion im großen Maßstab erwägen Sie Docker Swarm (verwendet Compose-Dateien nativ) oder Kubernetes. Der Vorteil von Compose ist, dass Ihre Entwicklungskonfiguration direkt die Produktion informiert und Umgebungsunterschiede reduziert.