Docker Compose: down vs stop erklärt

Die kurze Antwort

docker compose stop stoppt die Container und lässt sie auf dem Datenträger bestehen. docker compose down stoppt die Container und löscht anschließend die Container sowie das Netzwerk, das Compose für das Projekt erstellt hat. Keiner der beiden Befehle verändert ein benanntes Volume. Ihre Datenbank wird erst gelöscht, wenn Sie -v hinzufügen, wie in docker compose down -v. Dadurch werden die benannten Volumes entfernt, die im Abschnitt volumes der Compose-Datei deklariert sind.

Das ist der gesamte Unterschied in einem Absatz. Der restliche Leitfaden belegt ihn anhand eines Postgres-Volumes, dessen Fortbestand Sie nach down beobachten können und das durch down -v gelöscht wird. Außerdem werden die beiden Fälle erläutert, in denen Sie --force-recreate benötigen.

docker compose stop: Die Container bleiben erhalten

stop sendet SIGTERM an den Hauptprozess in jedem Container, wartet und sendet anschließend SIGKILL, wenn der Prozess noch läuft. Die Standardwartezeit beträgt 10 Sekunden. -t ändert diese Wartezeit. Es wird nichts gelöscht. Der Container behält seine ID, seine beschreibbare Schicht, seine IP-Reservierung und seine Logs.

docker compose stop
docker compose ps -a

docker compose ps zeigt allein nur laufende Container an. Nach stop wird deshalb eine leere Tabelle ausgegeben, und man könnte annehmen, die Container seien gelöscht. ps -a schließt angehaltene Container ein. Dort sehen Sie neben jedem Dienst Exited (0). Mit docker compose start starten Sie sie wieder. Dabei werden exakt dieselben Container wiederverwendet.

Da die Container weiterhin vorhanden sind, bleiben alle darin geschriebenen Daten erhalten, die nicht in einem Volume liegen. Dazu gehören auch ein Paket, das Sie manuell mit docker compose exec installiert haben, und eine Konfigurationsdatei, die Sie innerhalb des Containers bearbeitet haben. Das ist der praktische Grund, beim Debugging stop zu bevorzugen: Sie können in denselben Zustand zurückkehren.

docker compose down: Container und Netzwerke werden entfernt

down stoppt die Container und entfernt sie anschließend zusammen mit dem Standardnetzwerk, das Compose für das Projekt erstellt hat. Die Docker-Dokumentation beschreibt den Befehl als Vorgang zum Stoppen von Containern und Entfernen von Containern, Netzwerken, Volumes und Images, die von up erstellt wurden. Die Teile zu Volumes und Images werden jedoch nur ausgeführt, wenn Sie sie mit -v und --rmi anfordern.

docker compose down
docker compose ps -a
docker network ls

Nach down gibt ps -a für das Projekt nichts aus, und das Netzwerk <project>_default ist nicht mehr vorhanden. Der Projektname wird aus dem Verzeichnisnamen übernommen, sofern Sie nicht name: in der Compose-Datei setzen oder -p übergeben. Jede Änderung in der beschreibbaren Ebene eines Containers ist jetzt nicht mehr wiederherstellbar. Behandeln Sie down daher als Befehl, der den Container verwirft und die Daten in Volumes beibehält.

Wenn Sie den Befehl im falschen Verzeichnis ausführen, erhalten Sie no configuration file provided: not found. Compose weiß nicht, welches Projekt Sie meinen, und verweigert die Ausführung. Verwenden Sie docker compose -f /srv/myapp/compose.yaml down, wenn Sie sich nicht im Projektverzeichnis befinden.

Löscht docker compose down meine Volumes?

Nein. Ein benanntes Volume, das unter dem Schlüssel volumes auf der obersten Ebene deklariert ist, bleibt über down hinaus bestehen. Es bleibt auch erhalten, wenn der Container gelöscht wird, an den es angebunden war. Das ist die häufigste Sorge bei diesem Befehl. Bei Compose v2 ist die Antwort unverändert.

Richten Sie einen Stack ein, den Sie testen können. Speichern Sie Folgendes in compose.yaml in einem leeren Verzeichnis namens voltest.

services:
  db:
    image: postgres:16.4
    restart: unless-stopped
    environment:
      POSTGRES_PASSWORD: example
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

Starten Sie den Stack und schreiben Sie eine Zeile, die Sie später wiedererkennen.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "create table marker (note text);"
docker compose exec -T db psql -U postgres -c "insert into marker values ('survived');"

Löschen Sie nun den Container und prüfen Sie das Volume.

docker compose down
docker volume ls

Die Ausgabe führt voltest_pgdata weiterhin auf. Der Container ist gelöscht, die Daten sind jedoch noch vorhanden. Starten Sie den Stack erneut und lesen Sie die Zeile aus.

docker compose up -d
sleep 10
docker compose exec -T db psql -U postgres -c "select * from marker;"

Sie erhalten eine Zeile mit survived. Der neue Container ist ein anderer Container mit einer anderen ID, der an dasselbe Volume angebunden ist. Einen umfassenderen Überblick bietet der Leitfaden zu den Compose-Grundlagen. Er vergleicht benannte Volumes mit Bind-Mounts und erläutert, wo die jeweiligen Daten tatsächlich auf dem Host liegen.

Was down -v genau zerstört

-v (Langform --volumes) entfernt die in Abschnitt volumes der Compose-Datei deklarierten benannten Volumes sowie an die Container angehängte anonyme Volumes. Führen Sie den Befehl für denselben Stack aus.

docker compose down -v
docker volume ls

voltest_pgdata wird nicht mehr aufgeführt. Starten Sie den Stack erneut. Der Postgres-Entrypoint findet dann ein leeres Datenverzeichnis und initialisiert einen neuen Cluster. Das Container-Log sagt dies ausdrücklich.

The files belonging to this database system will be owned by user "postgres".
PostgreSQL init process complete; ready for start up.

Wenn dieser Block bei einem Stack erscheint, der seit Monaten läuft, wurde das Volume entfernt. Ihre marker-Tabelle ist nicht mehr vorhanden. Der einzige Weg zurück ist ein Backup.

Bestimmter Speicher wird von -v nie entfernt. Ein Bind-Mount verweist auf einen Pfad auf dem Host. Docker hebt daher nur den Mount auf, und Ihre Dateien bleiben an ihrem Speicherort. Ein mit external: true markiertes Volume ist als Ressource deklariert, die außerhalb dieses Projekts verwaltet wird. Compose entfernt es daher nie. Ein benanntes Volume, das Sie vor der Ausführung von down -v aus der Compose-Datei gelöscht haben, ist nicht mehr deklariert. Compose kennt es daher nicht mehr und lässt es als verwaistes Volume für docker volume prune zurück.

Dieser letzte Fall tritt bei einer Umstrukturierung häufig auf. Entfernen Sie einen Dienst und sein Volume aus der Datei und führen Sie anschließend down -v aus, bleibt das Volume bestehen, weil es in der Datei nicht mehr erwähnt wird. Führen Sie down -v vor dem Bearbeiten der Datei aus, nicht danach.

Wann Sie tatsächlich --force-recreate benötigen

docker compose up -d baut nicht jedes Mal alles neu auf. Compose speichert einen Hash der aufgelösten Konfiguration jedes Dienstes als Label am Container. Stimmen der Hash und die Image-ID überein, bleibt der Container unverändert, und Sie erhalten Container voltest-db-1 Running statt Recreated. Dieses Verhalten ist fast immer erwünscht, weil up -d dadurch wiederholt sicher ausgeführt werden kann.

Das erklärt auch, warum manche Änderungen scheinbar keine Wirkung haben. Compose hasht die aufgelöste Dienstdefinition, nicht den Inhalt der Dateien, auf die diese Definition verweist. Eine in den Container eingebundene Konfigurationsdatei, die nur beim Start eingelesen wird, löst beim Bearbeiten keine Neuerstellung aus, weil sich der Mount-Pfad nicht geändert hat. Der Dienst läuft mit den Werten weiter, die er beim Boot eingelesen hat.

docker compose up -d --force-recreate

Dieser Befehl stoppt und entfernt jeden Container und erstellt ihn anhand derselben Definition neu. Verwenden Sie ihn nach einer Änderung an einer eingebundenen Konfigurationsdatei sowie dann, wenn ein Container in einen Zustand geraten ist, den Sie nicht erklären können. Volumes bleiben unverändert, daher bleibt eine Datenbank bei einer erzwungenen Neuerstellung erhalten. Um ein neueres Image unter demselben Tag zu übernehmen, benötigen Sie zusätzlich den Pull-Vorgang.

docker compose pull
docker compose up -d

pull ruft die neue Image-ID ab. Anschließend erkennt up -d, dass sich die Image-ID vom laufenden Container unterscheidet, und erstellt ihn selbstständig neu. Wenn Sie --force-recreate ohne pull hinzufügen, erhalten Sie einen neuen Container aus demselben alten Image. Daher ist die Aussage „Ich habe eine erzwungene Neuerstellung durchgeführt, aber es ist immer noch die alte Version“ so häufig.

docker compose restart führt nichts davon aus. Der Befehl startet die vorhandenen Container neu und liest die Compose-Datei überhaupt nicht erneut ein. Eine geänderte Umgebungsvariable oder eine geänderte Portzuordnung wird daher nicht übernommen. Wenn Sie die Datei bearbeitet haben, verwenden Sie up -d.

Das grundlegende Modell

Container sind ersetzbar. Ein Container besteht aus einem Prozess und einer dünnen beschreibbaren Schicht. Compose kann anhand der Datei in etwa einer Sekunde einen identischen Container erstellen. Volumes sind nicht ersetzbar. Sie enthalten die einzige Kopie des Zustands, die keine Datei in Ihrem Repository neu erzeugen kann.

Jedes Compose-Kommando entspricht dieser Trennung. stop und start behalten den Container bei. down und up ersetzen den Container und behalten das Volume bei. down -v ist das einzige reguläre Kommando, das den Zustand entfernt. Deshalb ist dafür ein explizites Flag erforderlich. Bevor Sie es auf einem echten System eingeben, vergewissern Sie sich, dass ein Backup vorhanden ist und mindestens einmal wiederhergestellt wurde.

Für Secrets gilt dieselbe Logik. Ein über POSTGRES_PASSWORD gesetztes Passwort wird nur beim ersten Initialisieren der Datenbank gelesen. Wenn Sie es in Ihrer Umgebungsdatei ändern und up -d ausführen, erhalten Sie daher password authentication failed for user "postgres". Der Container ist neu, das Volume ist alt. Das alte Volume enthält weiterhin das alte Passwort. So löst Compose env-Dateien und Secrets auf erklärt, welche Ebene Vorrang hat, wenn dieselbe Variable zweimal gesetzt wird.

Fehlerursachen und die angezeigten Meldungen

no configuration file provided: not found bedeutet, dass Compose in einem Verzeichnis ohne compose.yaml und ohne docker-compose.yml ausgeführt wird. Übergeben Sie -f mit dem vollständigen Pfad.

network voltest_default has active endpoints bei down bedeutet, dass ein Container außerhalb dieses Projekts mit dem Projektnetzwerk verbunden ist. Meist wurde er manuell mit docker run --network gestartet. Entfernen Sie diesen Container und führen Sie anschließend erneut down aus.

Found orphan containers ([voltest-old-1]) for this project wird angezeigt, nachdem Sie einen Dienst umbenannt oder gelöscht haben. Der alte Container trägt weiterhin das Projektlabel. docker compose down --remove-orphans entfernt diese Container. Der Befehl kann gefahrlos für einen intakten Stack ausgeführt werden.

Error response from daemon: remove voltest_pgdata: volume is in use bei einem manuellen docker volume rm bedeutet, dass noch ein Container auf das Volume verweist. Das gilt auch für angehaltene Container. Führen Sie zuerst docker compose down aus und entfernen Sie anschließend das Volume. Alternativ können Sie einfach down -v verwenden. Bei einem größeren Projekt zeigt ein Compose-Stack mit mehreren Diensten, wie viele Volumes sich in einem Projekt ansammeln können.

FAQ

Löscht docker compose down meine Datenbank?

Nein, sofern die Datenbank in einem benannten Volume oder einem Bind-Mount liegt. down entfernt die Container und das Projektnetzwerk. Das Volume bleibt mit seinen unveränderten Daten auf dem Datenträger. Beim nächsten docker compose up -d wird ein neuer Container mit demselben Volume verbunden, und die Daten sind wieder vorhanden. Nur docker compose down -v entfernt benannte Volumes, und auch nur diejenigen, die im Abschnitt volumes der Compose-Datei deklariert sind.

Was ist der Unterschied zwischen stop und down, wenn ich einen Container später wieder verwenden möchte?

stop behält den Container bei. docker compose start startet daher denselben Container mit derselben beschreibbaren Schicht erneut. Alles, was Sie manuell im Container installiert oder bearbeitet haben, bleibt erhalten. down löscht den Container. Der nächste up -d erstellt dann einen neuen Container aus dem Image, und diese manuellen Änderungen gehen verloren. Verwenden Sie beim Debuggen stop.

Wie entferne ich alles, was ein Compose-Projekt erstellt hat?

docker compose down -v --rmi all --remove-orphans entfernt die Container, das Projektnetzwerk, die in der Datei deklarierten benannten Volumes, die von den Diensten verwendeten Images sowie alle Container, die noch mit dem Projektnamen gekennzeichnet sind. Bind-Mounts und mit external: true gekennzeichnete Volumes werden nicht verändert. Prüfen Sie vor der Ausführung mit docker volume ls, welche Daten Sie dadurch verlieren würden.

Warum übernimmt mein Container die Änderung an einer eingebundenen Konfigurationsdatei nicht?

Compose entscheidet anhand eines Hashes der aufgelösten Dienstdefinition, ob ein Container neu erstellt werden muss. Der Inhalt einer eingebundenen Datei ist nicht Bestandteil dieses Hashes. Der Pfad hat sich nicht geändert. Deshalb lässt Compose den Container mit den beim Start gelesenen Werten weiterlaufen. Führen Sie docker compose up -d --force-recreate aus, um einen neuen Container zu erstellen, der die Datei erneut einliest.

Warum funktioniert mein neues POSTGRES_PASSWORD nach der Änderung nicht?

Das Postgres-Image liest POSTGRES_PASSWORD nur ein, wenn es ein leeres Datenverzeichnis initialisiert. Ihr Volume enthält bereits einen initialisierten Cluster. Deshalb wird die Variable ignoriert, und das alte Passwort gilt weiterhin. Sie sehen password authentication failed for user "postgres". Ändern Sie das Passwort mit ALTER USER in der laufenden Datenbank. Alternativ können Sie die Daten verwerfen und mit docker compose down -v neu beginnen.