Docker Compose Grundlagen: compose.yaml, Befehle und typische Fehler

aktualisiert 30. Oktober 2026

Docker Compose beschreibt eine Anwendung aus mehreren Containern in einer einzigen YAML-Datei und startet, stoppt und überwacht alle Teile mit einem Befehl. Typisch ist eine Webanwendung mit Datenbank: Die Datei compose.yaml legt Images, Ports, Speicher und Netzwerk fest, docker compose up -d startet alles im Hintergrund. Nachfolgend stehen der Aufbau der Datei, ein lauffähiges Beispiel, die wichtigsten Befehle und die häufigsten Fehler.

Zuerst zur Schreibweise des Befehls. Laut der Versionsgeschichte in der Docker-Dokumentation erschien Compose V1 im Jahr 2014, ist in Python geschrieben und heißt docker-compose. Die heutigen Versionen V2 und V5 sind in Go geschrieben und laufen als docker compose ohne Bindestrich, wobei V5 funktional mit V2 identisch ist. Docker erklärte V1 im April 2022 für veraltet und entfernte es mit Docker Desktop 4.23.0 vom 11. September 2023, weil es keine Updates mehr erhielt.

Wann sich Docker Compose lohnt

Die Dokumentation nennt drei typische Einsatzfelder: Entwicklungsumgebungen, automatisierte Tests und Einzelhost-Deployments. Compose ersetzt eine mehrseitige Einrichtungsanleitung durch eine Datei und wenige Befehle. Für Tests entsteht die Umgebung mit docker compose up -d, nach dem Testlauf räumt docker compose down sie ab. Auf einem einzelnen Server ist auch Produktivbetrieb möglich, etwa auf einem eigenen VPS. Ändert sich ein Dienst nicht, verwendet Compose beim nächsten Start den vorhandenen Container weiter.

Docker Desktop bringt Compose mit. Unter Linux mit reiner Docker Engine kommt das Plugin aus dem Docker-Repository: sudo apt-get install docker-compose-plugin unter Debian und Ubuntu, sudo yum install docker-compose-plugin bei RPM-Distributionen. Ob es klappt, zeigt docker compose version.

Aufbau der compose.yaml

Compose und die Compose Specification bevorzugen den Dateinamen compose.yaml, erlaubt ist auch compose.yml. Aus Kompatibilitätsgründen werden zudem docker-compose.yaml und docker-compose.yml gelesen, bei mehreren Dateien gewinnt compose.yaml. Die alte Zeile version: ist obsolet und löst nur eine Warnung aus.

Die Dienste erreichen einander über ihren Namen, denn Compose trägt jeden Dienstnamen in einen internen DNS-Server ein. IP-Adressen eignen sich nicht, weil Docker sie bei jedem Start neu vergibt.

Beispiel: WordPress mit MariaDB

Das Beispiel kombiniert die Images wordpress und mariadb. Der Healthcheck folgt der Vorlage aus der MariaDB-Dokumentation. In ein leeres Verzeichnis kommen zwei Dateien, zuerst compose.yaml:

services:
  wordpress:
    image: wordpress
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_NAME: ${DB_NAME}
      WORDPRESS_DB_USER: ${DB_USER}
      WORDPRESS_DB_PASSWORD: ${DB_PASSWORD}
    volumes:
      - wp-data:/var/www/html
    depends_on:
      db:
        condition: service_healthy

  db:
    image: mariadb:lts
    restart: unless-stopped
    environment:
      MARIADB_DATABASE: ${DB_NAME}
      MARIADB_USER: ${DB_USER}
      MARIADB_PASSWORD: ${DB_PASSWORD}
      MARIADB_RANDOM_ROOT_PASSWORD: "1"
    volumes:
      - db-data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "healthcheck.sh", "--connect", "--innodb_initialized"]
      start_period: 10s
      interval: 10s
      timeout: 5s
      retries: 3

volumes:
  wp-data:
  db-data:

Daneben liegt die Datei .env mit eigenen Werten:

DB_NAME=wordpress
DB_USER=wpuser
DB_PASSWORD=ein-langes-zufaelliges-passwort

1. docker compose config zeigt die fertig aufgelöste Konfiguration mit eingesetzten Variablen.
2. docker compose up -d lädt die Images und startet zuerst db. wordpress folgt, sobald der Healthcheck besteht.
3. docker compose ps listet Status und Ports. Danach ist WordPress unter http://localhost:8080 erreichbar.

WORDPRESS_DB_HOST: db verweist auf den Dienstnamen. Der Eintrag 127.0.0.1:8080:80 macht den Port nur auf dem Host selbst erreichbar. MARIADB_DATABASE legt die Datenbank beim ersten Start an, denn der WordPress-Container erzeugt sie nicht selbst. Das zufällige Root-Passwort steht im Log von db.

Die wichtigsten Befehle

Variablen und .env

Compose liest die Datei .env im Projektverzeichnis automatisch und setzt ihre Werte an Platzhaltern wie ${DB_PASSWORD} ein. In den Container gelangt ein Wert dadurch noch nicht, dafür sorgen environment oder env_file. Bei gleichen Namen gewinnt die Shell-Umgebung vor --env-file, und dieses vor der .env. Mit ${VAR:-standard} lässt sich ein Standardwert vorgeben, ${VAR:?Fehlertext} bricht ab, wenn die Variable fehlt oder leer ist. Ein wörtliches Dollarzeichen schreibt man in der compose.yaml als $$.

Typische Fehler

Häufige Fragen

Weitere Anleitungen

SSH-Schlüssel erstellen mit ssh-keygen: Ed25519, Passphrase und Server-Zugang

SSH-Schlüssel erstellen mit ssh-keygen: Ed25519, ECDSA oder RSA, Passphrase, ssh-agent, Kopie auf den Server, Dateirechte sowie Windows und macOS.