Docker Compose verstehen: Services, Volumes, Netzwerke

Im mit , mit dem jede App

später ihre Domain und ihr HTTPS bekommt.

Schritt 4: Konfiguration – Umgebungsvariablen, .env und Healthchecks

Fast jede Anwendung wird über Umgebungsvariablen konfiguriert. Zwei Wege:

services:

  app:

    image: beispiel/app:1.0

    environment:

      - TZ=Europe/Berlin

      - APP_PORT=3000

Geheimnisse (Passwörter, Tokens) gehören nicht in die compose.yaml, sondern in

eine .env-Datei im selben Ordner. Compose liest sie automatisch:

echo "DB_PASSWORD=EIN_LANGES_ZUFALLSPASSWORT" > .env

services:

  db:

    image: postgres:18

    environment:

      - POSTGRES_PASSWORD=${DB_PASSWORD}

⚠️ .env nie ins Backup-Repo pushen

Die .env enthält Klartext-Geheimnisse. Nimm sie in eine .gitignore auf, falls du

deine Compose-Dateien versionierst, und sichere sie getrennt (verschlüsselt).

So prüfst du, ob Compose deine Datei versteht und die .env-Werte richtig

einsetzt – ohne etwas zu starten:

docker compose config

config löst alle Variablen auf und gibt die fertige, normalisierte Konfiguration

aus:

name: compose-demo

services:

  db:

    environment:

      POSTGRES_PASSWORD: EIN_LANGES_ZUFALLSPASSWORT

    image: postgres:18

    networks:

      default: null

Steht dort dein echter Wert statt ${DB_PASSWORD}, greift die .env. Brauchst

du nur einen schnellen Syntax-Check ohne die ganze Ausgabe, nimm

docker compose config --quiet – kommt nichts zurück (Exit-Code 0), ist die Datei

gültig. Genau das ist auch dein erster Griff bei YAML-Fehlern (siehe unten).

Ein Healthcheck sagt Docker, wann ein Dienst wirklich bereit ist – die Basis

dafür, dass abhängige Dienste erst dann starten:

services:

  db:

    image: postgres:18

    environment:

      - POSTGRES_PASSWORD=${DB_PASSWORD}

    healthcheck:

      test: ["CMD-SHELL", "pg_isready -U postgres"]

      interval: 10s

      timeout: 5s

      retries: 5



  app:

    image: beispiel/app:1.0

    depends_on:

      db:

        condition: service_healthy

Mit condition: service_healthy startet app erst, wenn der Healthcheck von db

grün ist – das häufigste „warum verbindet sich meine App nicht zur Datenbank?"

verschwindet damit. Die vier Healthcheck-Felder bedeuten: test ist der Befehl,

der im Container läuft (Exit-Code 0 = gesund), interval der Abstand zwischen

den Prüfungen, timeout wie lange eine Prüfung dauern darf, und retries

wie viele Fehlversuche in Folge nötig sind, bevor der Container als unhealthy gilt.

Den aktuellen Zustand zeigt die STATUS-Spalte von docker compose ps als

(healthy) bzw. (unhealthy).

Schritt 5: Der Betriebs-Werkzeugkasten

Diese Befehle brauchst du täglich – immer im Projektordner ausführen:

docker compose up -d        # starten / Änderungen anwenden

docker compose ps           # Status der Services

docker compose logs -f web  # Logs live mitlesen (Strg+C beendet nur das Ansehen)

docker compose exec web sh  # Shell im laufenden Container

docker compose restart web  # einen einzelnen Dienst neu starten

docker compose stop         # anhalten, ohne Container/Netzwerk zu entfernen

docker compose pull         # neue Image-Versionen holen

docker compose down         # Stack stoppen und entfernen (Volumes bleiben)

Fast alle Befehle lassen sich auf einen Service einschränken, indem du seinen

Namen anhängst (docker compose logs -f web, docker compose restart web) – ohne

Namen gelten sie für den ganzen Stack. Der Unterschied zwischen stop und down:

stop hält die Container nur an (mit start geht's weiter), down entfernt sie

samt Netzwerk (die Named Volumes bleiben in beiden Fällen).

Ein Update läuft fast immer nach demselben Muster: Tag in der compose.yaml

hochsetzen → docker compose pull → docker compose up -d. Compose ersetzt nur die

Container, deren Image sich geändert hat.

Schritt 6: Alles zusammen – ein realistischer App-Stack

So sieht das Muster aus, das dir in den App-Tutorials immer wieder begegnet: eine

Anwendung plus ihre Datenbank. Diese Datei bündelt alles aus den Schritten 1–4 –

lies sie einmal komplett, dann hast du 90 % jeder späteren compose.yaml

verstanden:

services:

  app:

    image: beispiel/app:1.4          # feste Version, kein latest

    ports:

      - "8080:3000"                  # nur die App ist von außen erreichbar

    environment:

      - TZ=Europe/Berlin

      - DATABASE_URL=postgres://app:${DB_PASSWORD}@db:5432/app

    volumes:

      - appdata:/data                # persistente App-Daten (Named Volume)

    depends_on:

      db:

        condition: service_healthy   # startet erst, wenn db bereit ist

    restart: unless-stopped



  db:

    image: postgres:18

    environment:

      - POSTGRES_USER=app

      - POSTGRES_PASSWORD=${DB_PASSWORD}

      - POSTGRES_DB=app

    volumes:

      - dbdata:/var/lib/postgresql/data   # die eigentlichen Datenbank-Dateien

    healthcheck:

      test: ["CMD-SHELL", "pg_isready -U app"]

      interval: 10s

      timeout: 5s

      retries: 5

    restart: unless-stopped

    # kein ports: – die Datenbank ist NUR intern über den Namen "db" erreichbar



volumes:

  appdata:

  dbdata:

Drei Design-Entscheidungen, die du dir merken solltest:

1. 
   Nur app hat ports:. Die Datenbank braucht keinen offenen Host-Port – die
   App erreicht sie intern über den Hostnamen db (die DATABASE_URL zeigt genau
   dorthin). Ein nicht veröffentlichter Port ist ein Port, den niemand aus dem
   Internet angreifen kann.


2. 
   Zwei getrennte Named Volumes. App-Daten und Datenbank-Dateien liegen sauber
   getrennt – das macht spätere Backups und Restores nachvollziehbar.


3. 
   Passwort nur als ${DB_PASSWORD}. Der echte Wert steht in der .env, nicht
   in dieser Datei. Dieselbe compose.yaml kann so gefahrlos geteilt werden.

Genau dieses Grundgerüst – App nach außen, Datenbank nur intern, Daten in Named

Volumes, Secrets in der .env – wiederholt sich in Nextcloud, Vaultwarden,

Paperless und den meisten anderen Rezepten.

Wenn es nicht funktioniert

Symptom: yaml: line 7: did not find expected key (oder ähnliche YAML-Fehler)

Ursache & Lösung: YAML ist einrückungssensibel – ausschließlich Leerzeichen,

niemals Tabs, und pro Ebene konsistent (üblich: 2 Leerzeichen). Prüfe die Datei

ohne sie zu starten: docker compose config löst alles auf und meckert genau die

falsche Zeile an.

Symptom: Error ... address already in use beim up

Ursache & Lösung: Der Host-Port (links in 8080:80) ist schon belegt. Finde den

Beleger mit sudo ss -tlnp | grep 8080 oder wähle einen anderen Host-Port. Zwei

Container dürfen sich denselben Host-Port nicht teilen.

Symptom: Eine App findet ihre Datenbank nicht (could not translate host name).

Ursache & Lösung: Als Hostname muss der Service-Name stehen (z. B. db),

nicht localhost. Innerhalb eines Containers ist localhost der Container selbst,

nicht der Nachbar-Service. Und: Beide Services müssen im selben Compose-Projekt

(derselben Datei) liegen.

Symptom: Nach docker compose down sind alle Daten weg.

Ursache & Lösung: Entweder lag das Volume nicht als Named Volume unter

volumes: vor (dann war es nur der vergängliche Container-Speicher), oder es wurde

down -v verwendet. Persistente Dienste immer mit deklariertem Named Volume fahren.

Symptom: docker-compose: command not found

Ursache & Lösung: Das ist das alte Compose v1 (mit Bindestrich). Aktuell ist

docker compose (mit Leerzeichen, Plugin). Falls es fehlt:

sudo apt install docker-compose-plugin (siehe .