Docker Compose Befehle für produktive Server

Die Compose-Befehle, die Sie tatsächlich verwenden

Docker Compose enthält mehr als vierzig Unterbefehle. Im täglichen Serverbetrieb benötigen Sie etwa ein Dutzend. Diese Seite ordnet sie nach der jeweiligen Aufgabe, nennt für jeden Befehl einen konkreten Grund und verweist auf die ausführliche Erklärung, wenn ein Befehl eine wichtige Besonderheit hat.

Alle Beispiele hier verwenden Compose V2: docker compose mit einem Leerzeichen, nicht das alte docker-compose-Skript. V2 ist ein Go-Plugin, das zusammen mit Docker Engine installiert wird. V1 ist in aktuellen Paketen nicht mehr enthalten. Deshalb ist ein docker-compose: command not found auf einem frisch installierten Ubuntu-System im Juli 2026 erwartbar und kein Fehler. Prüfen Sie dies mit docker compose version. Wenn der Befehl keine Ausgabe liefert, installieren Sie das Paket docker-compose-plugin.

Jeder folgende Befehl wird aus dem Verzeichnis ausgeführt, das Ihre compose.yaml enthält. Compose übernimmt den Projektnamen aus diesem Verzeichnis und sucht die Datei relativ dazu. Führen Sie denselben Befehl eine Ebene höher aus, beendet sich Compose mit no configuration file provided: not found. Wenn Ihnen das Dateiformat noch nicht vertraut ist, beginnen Sie mit einer ersten Compose-Datei auf einem VPS und kehren Sie anschließend für die Befehle hierher zurück.

Lifecycle: die vier Befehle und der eine, der Container entfernt

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

up -d erstellt das Netzwerk und die Container, startet die Container und kehrt anschließend zurück. Der Befehl kehrt zurück, sobald die Container erstellt wurden. Deshalb schlägt ein Deploy-Skript, das danach eine curl-Prüfung ausführt, beim ersten Versuch häufig fehl. up -d --wait wartet, bis jeder Dienst mit einem definierten Healthcheck den Status healthy meldet, und beendet sich mit einem Wert ungleich null, wenn ein Dienst diesen Status nie erreicht. Das Flag ist nur so zuverlässig wie die dahinterliegende Prüfung. Schreiben Sie daher einen Healthcheck, dem Compose vertrauen kann, bevor Sie sich in der Automatisierung darauf verlassen.

stop hält die Container an und behält sie bei. start startet anschließend dieselben Container mit derselben beschreibbaren Schicht. down stoppt die Container und entfernt danach die Container sowie das Projektnetzwerk. Alles, was innerhalb des Containers und außerhalb eines Volumes gespeichert wurde, geht dabei verloren. Dies ist das folgenschwerste Missverständnis bei Compose. Der vollständige Unterschied zwischen down und stop zeigt, wo sich das auswirkt.

restart ist kein Reload. Der Befehl stoppt und startet denselben Container mit der bereits vorhandenen Konfiguration. Eine geänderte Umgebungsvariable, ein neuer Image-Tag oder eine bearbeitete Portzuordnung haben daher keinerlei Wirkung. Um eine Änderung an der Datei anzuwenden, führen Sie up -d erneut aus. Compose vergleicht jeden Dienst mit seinem laufenden Container und erstellt nur die Container neu, deren Konfiguration geändert wurde.

Änderung anwenden: neu erstellen, abrufen oder neu bauen

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

up -d führt nichts aus, wenn sich nichts geändert hat. Dadurch kann der Befehl sicher wiederholt ausgeführt werden. --force-recreate setzt diesen Vergleich außer Kraft und ersetzt jeden Container, auch wenn die Konfiguration identisch ist. Das ist der schnellste Weg, einen ungewöhnlichen Zustand im Container zu beseitigen.

Das Aktualisieren eines Images erfordert zwei Befehle, weil sie unterschiedliche Aufgaben erfüllen. pull lädt das aktuelle Image für jedes in der Datei angegebene Tag herunter. up -d erkennt anschließend, dass die Image-ID des Dienstes nicht mehr mit der des laufenden Containers übereinstimmt, und erstellt den Container neu. Wenn der Pull übersprungen wird, lässt up -d das latest des letzten Monats ohne Fehlermeldung weiterlaufen.

build gilt für Dienste, die einen Abschnitt build: statt eines Abschnitts image: deklarieren. up -d --build baut das Image und startet den Dienst in einem Schritt. Das ist der übliche Ablauf, während Sie den Code ändern. Verwenden Sie --no-cache nur, wenn eine zwischengespeicherte Ebene offensichtlich veraltet ist, da dadurch jede Ebene von Grund auf neu gebaut wird.

Was ausgeführt wird

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

ps listet nur laufende Container auf. Ein Dienst, der beim Start abgestürzt ist, bleibt dort unsichtbar, bis Sie -a hinzufügen. Ein Container, der in ps fehlt, während ps -a ihn als Exited (1) anzeigt, ist daher das normale Bild eines Startfehlers. Lesen Sie zuerst den Exit-Code und anschließend die Logs.

logs -f verfolgt alle Dienste gleichzeitig und stellt jeder Zeile den Namen des Dienstes voran. Diese Ansicht ist sinnvoll, wenn Dienste miteinander kommunizieren und die Reihenfolge der Ereignisse relevant ist. Geben Sie einen Dienst an, um die Ausgabe einzugrenzen. --tail=100 ist bei einem Container wichtig, der seit einem Monat läuft, weil die Standardausgabe die gesamte Historie ausgibt und das Terminal überflutet. --since 15m beantwortet die Frage, die sich normalerweise stellt: Was ist während des gerade durchgeführten Neustarts passiert?

top listet die Prozesse innerhalb jedes Containers auf. Damit lässt sich unterscheiden, ob der Container läuft oder der darin ausgeführte Prozess läuft. ls verlässt das aktuelle Verzeichnis und listet alle Compose-Projekte auf dem Host mit ihrem Status auf. So finden Sie den Stack, den Sie vor drei Monaten gestartet haben.

Eine Shell innerhalb eines Dienstes öffnen

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

exec führt einen Befehl innerhalb eines bereits laufenden Containers aus. run startet einen neuen Container anhand derselben Dienstdefinition. Das benötigen Sie, wenn der Dienst nicht lange genug läuft, um sich per exec mit ihm zu verbinden. Verwenden Sie run immer zusammen mit --rm. Ohne diese Option hinterlässt jeder Aufruf einen gestoppten Container. Diese sammeln sich an, bis docker compose ps -a nicht mehr lesbar ist.

Testen Sie zuerst sh und erst danach bash. Auf Alpine basierende Images enthalten kein bash. Der Fehler lautet exec: "bash": executable file not found in $PATH. Wenn Sie --no-deps zu run hinzufügen, überspringt der Befehl die Abhängigkeiten des Dienstes. Dadurch wird bei einer schnellen Konfigurationsprüfung nicht die gesamte Datenbank gestartet.

Mit run --rm web env sehen Sie am schnellsten die Umgebung, die ein Dienst tatsächlich erhalten hat, nachdem jede .env-Datei, jeder environment:-Block und jede Shell-Variable zusammengeführt wurde. Wenn ein Wert falsch ist, liegt das meist an der Reihenfolge der Zusammenführung. Wie Compose Umgebungsdateien und Secrets auflöst erläutert, welche Quelle Vorrang hat.

Netzwerke, Ports und Namensauflösung

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

Compose legt jeden Dienst in einem gemeinsamen Projektnetzwerk an. Der Name jedes Dienstes ist darin ein DNS-Name. Wenn die Namensauflösung funktioniert, gibt getent hosts db innerhalb von web die IP-Adresse des Containers aus. Wenn sie nicht funktioniert, wird nichts ausgegeben. Damit lässt sich in zwei Sekunden prüfen, ob diese Container einander erreichen können. Wird der Name aufgelöst, aber die Verbindung abgelehnt, lauscht der Prozess in db an 127.0.0.1 statt an 0.0.0.0. Deshalb nimmt er keine Pakete von einem anderen Container an. Weitere Informationen zu diesem Modell finden Sie unter Funktionsweise von Compose-Netzwerken und der DNS-Auflösung für Dienste.

port web 80 gibt die Hostadresse und den Port aus, unter denen ein Container-Port veröffentlicht ist. Das erspart das Raten, wenn die Zuordnung aus einer Variablen stammt. Beim Veröffentlichen eines Ports wird außerdem eine Firewall-Regel erstellt, die Docker selbst verwaltet. Diese Regel wird vor Ihren eigenen Regeln ausgewertet. Dadurch kann ein Dienst, den Sie für privat hielten, aus dem Internet erreichbar sein. Dieser Fall wird unter Warum veröffentlichte Docker-Ports ufw umgehen behandelt.

Volumes und Daten

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

config --volumes gibt die vom Projekt deklarierten benannten Volumes aus, jeweils eines pro Zeile. Diese Liste müssen Sie sichern. cp kopiert eine Datei in einen Container oder aus einem Container heraus, ohne eine Shell zu öffnen. Verwenden Sie dafür die Form service:path auf der Seite des Containers.

down -v entfernt diese benannten Volumes zusammen mit den Containern. Dieser Befehl eignet sich zum Entfernen eines Test-Stacks. Für Daten, die Sie benötigen, ist er ungeeignet, da keine Bestätigung erfolgt und der Vorgang nicht rückgängig gemacht werden kann. Bind-Mounts bleiben erhalten, weil sie im Dateisystem des Hosts liegen. Dieser Unterschied beim möglichen Schadensumfang ist ein Grund, bewusst zwischen Bind-Mounts und benannten Volumes zu wählen.

Bereinigung, die Speicherplatz freigibt, ohne Daten zu verlieren

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

--remove-orphans löscht Container, die zum Projekt gehören, aber in der Datei nicht mehr aufgeführt sind. Genau das passiert nach der Umbenennung eines Dienstes. Ohne diesen Befehl laufen die Container weiter und sind für docker compose ps nicht sichtbar.

docker system df zeigt vor dem Löschen, wofür der Speicherplatz verwendet wird. Die Ausgabe trennt Images, Container, lokale Volumes und den Build-Cache und weist für jeden Bereich eine freigebbare Größe aus. image prune -a entfernt alle Images, auf die kein Tag verweist. Auf einem System, das mehrere Versionen eines großen Images abgerufen hat, bringt das normalerweise den größten Speichergewinn. builder prune leert den Build-Cache. Dieser wächst auf jedem Server, der eigene Images erstellt, unbemerkt weiter.

Keiner dieser Befehle greift ein benanntes Volume an. Nur docker volume prune und docker compose down -v tun das.

Die Datei prüfen, bevor sie Probleme verursacht

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

config --quiet validiert die Datei und gibt bei Erfolg nichts aus. Daher gehört der Befehl in einen Pre-Deploy-Schritt oder einen Git-Hook. Das einfache config gibt die vollständig zusammengeführte und interpolierte Datei aus. Damit prüfen Sie, ob eine Variable aufgelöst und eine Override-Datei wie erwartet eingebunden wurde. Eine nicht gesetzte Variable erscheint dort mit einem leeren Wert, zusammen mit der Warnung The "X" variable is not set. Defaulting to a blank string.

--dry-run ist ein globales Flag und kein Flag des Subcommands. Es steht daher vor up. Der Befehl gibt jede Aktion aus, die Compose ausführen würde, und nimmt keine Änderungen vor. Diese 30 Sekunden sind gut investiert, bevor Sie bei einem wichtigen Stack ein down ausführen.

Arbeiten mit Dateien, Profilen und Projekten

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

Mehrere -f-Flags werden in der angegebenen Reihenfolge zusammengeführt. Spätere Dateien überschreiben frühere Dateien schlüsselweise. Das ist die übliche Methode, um eine Basisdatei mit einer kleinen Produktionsüberschreibung zu verwenden. Für Listen und Zuordnungen gelten jedoch andere Regeln. Lesen Sie daher wie Compose mehrere Dateien zusammenführt, bevor Sie eine unerwartete Konfiguration untersuchen.

--profile startet Dienste, die mit diesem Profil gekennzeichnet sind, zusätzlich zu den Diensten ohne Profil. Dadurch bleiben Debugging-Werkzeuge aus einem normalen up heraus. -p legt den Projektnamen fest. Dadurch können zwei Kopien desselben Stacks parallel mit getrennten Netzwerken und getrennten Volume-Namen ausgeführt werden. Der Stack wird nach einem Reboot nicht durch einen manuell eingegebenen Befehl wiederhergestellt. Stattdessen übernimmt dies eine Unit, wie unter Compose-Stacks beim Booten starten beschrieben.

FAQ

Was hat docker-compose mit einem Bindestrich ersetzt?

Compose V2, aufgerufen als docker compose mit einem Leerzeichen. Es ist ein in Docker Engine gebündeltes Plugin. Das Python-Tool aus V1 wird von aktuellen Paketen nicht mehr installiert. Wenn die Schreibweise mit Leerzeichen keine Ausgabe erzeugt, installieren Sie das Paket docker-compose-plugin für Ihre Distribution. Aktualisieren Sie alte Skripte auf die Schreibweise mit Leerzeichen, statt einen Alias hinzuzufügen, weil V2 über Flags verfügt, die es in V1 nicht gab.

Warum übernimmt docker compose restart meine Konfigurationsänderung nicht?

restart stoppt und startet den vorhandenen Container mit der Konfiguration, mit der er erstellt wurde. compose.yaml wird dabei nie erneut eingelesen. Änderungen an Umgebungsvariablen, Ports, Volumes oder dem Image-Tag erfordern docker compose up -d. Dieser Befehl vergleicht jeden Dienst mit seinem laufenden Container und erstellt Container neu, wenn sie voneinander abweichen. Fügen Sie --force-recreate hinzu, wenn der Container auch dann ersetzt werden soll, wenn sich an der Datei nichts geändert hat.

Wie aktualisiere ich einen Dienst auf ein neueres Image?

Führen Sie docker compose pull und anschließend docker compose up -d aus. Der Pull-Vorgang lädt für jedes Tag in der Datei das aktuelle Image herunter. up -d erstellt jeden Dienst neu, dessen Image-ID nicht mehr mit der seines Containers übereinstimmt. Wenn Sie up -d allein ausführen, wird das bereits lokal gespeicherte Image wiederverwendet. Dadurch kann ein Stack, der auf latest festgelegt ist, monatelang mit einem alten Build laufen, ohne eine Fehlermeldung auszugeben.

Welche Bereinigungsbefehle sind auf einem laufenden Server sicher?

docker system df, docker image prune -a und docker builder prune entfernen nur Images und den Cache. Laufende Dienste funktionieren weiter, und benannte Volumes bleiben unverändert. Gefährlich sind docker compose down -v und docker volume prune. Diese Befehle löschen benannte Volumes ohne Rückfrage. Führen Sie zuerst docker compose config --volumes aus, damit Sie wissen, welche Daten gefährdet sind.

Kann ich einen einzelnen Befehl ausführen, ohne den gesamten Stack zu starten?

Ja. docker compose run --rm --no-deps web sh startet einen einzelnen Container anhand der web-Dienstdefinition, überspringt dessen Abhängigkeiten und entfernt den Container beim Beenden. Verwenden Sie stattdessen exec, wenn der Container bereits läuft. exec verbindet sich mit dem laufenden Prozess und zeigt den tatsächlichen Zustand des Dienstes.