Docker Compose aktualisieren klingt nach zwei Befehlen: neue Images laden und Container neu starten. Bei Anwendungen mit Datenbank, Uploads oder Konfigurationsdateien gehört jedoch mehr dazu. Vor dem Update musst du wissen, wo die Daten liegen, welche Image-Version bisher lief und wie du bei einem Fehler zum letzten funktionierenden Stand zurückkehrst.

Diese Anleitung zeigt dir einen nachvollziehbaren Ablauf für einen Compose-Stack auf einem einzelnen Docker-Host. Du bereitest das Update vor, sicherst wichtige Daten, lädst neue Images und prüfst anschließend die Anwendung. Außerdem erfährst du, wann ein Rollback der Container genügt und wann du auch Daten aus einem Backup wiederherstellen musst.

Wenn du Docker und Compose zunächst einrichten möchtest, findest du die Grundlagen in unserem Beitrag Installation und Konfiguration von Docker.

Was passiert beim Aktualisieren eines Compose-Stacks?

Eine Compose-Datei beschreibt Dienste, Images, Netzwerke und Datenspeicher. Führst du docker compose up -d erneut aus, prüft Compose die bestehende Konfiguration. Hat sich das verwendete Image oder die Dienstkonfiguration geändert, wird der betreffende Container neu erstellt. Eingehängte Volumes bleiben dabei erhalten.

Das ist der entscheidende Unterschied zwischen Container und Volume: Der Container kann ersetzt werden, während ein benanntes Volume die Anwendungsdaten weiter speichert. Diese Trennung schützt Daten bei normalen Updates. Sie ersetzt aber kein Backup. Ein fehlerhaftes Update oder eine Datenbankmigration kann den Inhalt des Volumes verändern.

Die folgenden Befehle verwenden die aktuelle Schreibweise docker compose. Führe sie im Verzeichnis deines Projekts aus, in dem die compose.yaml liegt. Nutzt dein Stack zusätzliche Compose-Dateien, Profile oder einen ausdrücklich gesetzten Projektnamen, verwende bei jedem Schritt dieselben Optionen.

Docker Compose aktualisieren: Die Vorbereitung

Aktuellen Zustand festhalten

Beginne mit einem Blick auf die laufenden Dienste und ihre Images:

docker compose ps
docker compose images
docker compose config --images

Notiere die bisher verwendeten Image-Versionen und den Zustand der Container. Prüfe anschließend die Compose-Konfiguration:

docker compose config --quiet

Bleibt die Ausgabe leer und endet der Befehl ohne Fehler, konnte Compose die Konfiguration verarbeiten. Die Option --quiet ist hier bewusst gewählt: Eine vollständig ausgegebene Compose-Konfiguration kann eingesetzte Umgebungsvariablen und damit vertrauliche Werte enthalten.

Sichere vor dem Update außerdem deine compose.yaml, zusätzliche Compose-Dateien, benötigte .env-Dateien und relevante Anwendungskonfigurationen an einem geschützten Ort. Ein Versionsverwaltungssystem ist für die Compose-Dateien hilfreich. Zugangsdaten gehören dabei nicht ungeschützt in ein öffentliches Repository.

Release-Hinweise lesen und Version festlegen

Prüfe die Hinweise des jeweiligen Anwendungsprojekts. Besonders wichtig sind geänderte Umgebungsvariablen, neue Mindestversionen für Datenbanken und automatische Schema-Migrationen. Ein Sprung über mehrere Hauptversionen kann Zwischenschritte erfordern.

Für einen planbaren Rollback solltest du die bisherige und die neue Image-Version eindeutig kennen. Ein Tag wie latest kann später auf ein anderes Image zeigen. Ein festgelegter Versions-Tag oder ein Image-Digest macht den eingesetzten Stand besser nachvollziehbar. Auch Versions-Tags können technisch neu veröffentlicht werden; für eine exakt reproduzierbare Image-Auswahl ist ein Digest eindeutiger.

Volumes und Daten vor dem Update sichern

Prüfe in der Compose-Datei, welche Dienste benannte Volumes oder Bind-Mounts verwenden. Ein benanntes Volume kann beispielsweise Anwendungsdateien enthalten, während ein Bind-Mount auf ein Verzeichnis des Hosts zeigt. Beide Arten von Speicher müssen zu deinem Backup-Konzept passen. Eine Kopie der Compose-Datei enthält diese Daten nicht.

Für Datenbanken ist ein Backup mit dem Werkzeug der jeweiligen Datenbank meist der geeignete Ausgangspunkt, beispielsweise ein Datenbank-Dump oder ein dafür vorgesehener Sicherungsmechanismus. Kopiere die Dateien einer laufenden Datenbank nicht einfach mit tar und betrachte das Ergebnis als garantiert konsistent. Bei Dateivolumes kannst du einen ruhenden Dienst sichern oder einen geeigneten Snapshot verwenden.

Das folgende Beispiel zeigt eine Dateisicherung eines benannten Volumes, während die Anwendung gestoppt ist. Es ist für eine Linux- oder WSL-Shell geschrieben. Ersetze Volume-Namen und Host-Verzeichnis durch deine Werte:

docker compose stop app

docker run --rm \
  -v meinprojekt_app_data:/quelle:ro \
  -v /srv/compose-backups:/backup \
  alpine \
  tar -czf /backup/app_data-vor-update.tar.gz \
  -C /quelle .

Prüfe den tatsächlichen Volume-Namen mit docker volume ls. Compose ergänzt bei nicht externen Volumes üblicherweise den Projektnamen. Das Sicherungsverzeichnis auf dem Host muss bereits existieren und beschreibbar sein. Wenn dein Stack eine Datenbank enthält, richte dich für deren Sicherung nach den Vorgaben des Datenbankprodukts.

Ein Backup ist erst belastbar, wenn du weißt, wie du es wiederherstellst. Teste die Wiederherstellung wichtiger Daten deshalb regelmäßig in einer getrennten Umgebung.

Schritt für Schritt: Neue Images laden und Container aktualisieren

Images kannst du laden, während die bisherigen Container noch laufen:

docker compose pull

pull lädt die Images für Dienste mit einem image:-Eintrag. Laufende Container werden dadurch noch nicht ersetzt. Nutzt ein Dienst stattdessen build: und wird lokal aus einem Dockerfile gebaut, musst du ihn bei Änderungen mit docker compose build neu bauen.

Nachdem Backup und Versionsprüfung abgeschlossen sind, startest du das Update:

docker compose up -d

Compose erstellt Dienste mit geänderter Konfiguration oder geändertem Image neu und verwendet die eingebundenen Volumes weiter. Du musst den gesamten Stack dafür normalerweise nicht vorher mit docker compose down entfernen. Rechne bei neu erstellten Containern dennoch mit einer kurzen Unterbrechung der betroffenen Dienste.

Wenn du nur einen Dienst aktualisieren möchtest, kannst du ihn gezielt angeben. Das ist vor allem dann sinnvoll, wenn seine Abhängigkeiten unverändert bleiben sollen:

docker compose pull app
docker compose up -d --no-deps app

Ersetze app durch den Dienstnamen aus deiner Compose-Datei. Prüfe vorher, ob die neue Anwendungsversion eine Änderung an der Datenbank oder einem anderen Dienst verlangt.

Nach dem Update: Funktion und Daten prüfen

Kontrolliere zuerst den Container-Status und die aktuellen Protokolle:

docker compose ps
docker compose logs --tail=100

Ein laufender Container allein beweist noch nicht, dass die Anwendung funktioniert. Öffne ihre Oberfläche oder API und teste einen wichtigen Ablauf: Anmeldung, Lesen vorhandener Daten und – falls gefahrlos möglich – eine kleine Schreiboperation. Prüfe bei einer Datenbankanwendung außerdem, ob vorhandene Datensätze sichtbar sind und Migrationen ohne Fehler abgeschlossen wurden.

Hat ein Dienst einen passenden healthcheck in der Compose-Datei, zeigt Compose dessen Zustand an. Bei aktuellen Compose-Versionen kann docker compose up -d --wait auf „running“ beziehungsweise „healthy“ warten. Auch ein erfolgreicher Healthcheck ersetzt jedoch keinen kurzen Anwendungstest.

Rollback bei Docker Compose: Zur vorherigen Version zurückkehren

Wenn das neue Image Probleme macht, stelle zunächst fest, ob sich nur der Container oder auch die Daten geändert haben. Davon hängt der Rückweg ab.

Fall 1: Die Daten sind mit der alten Version kompatibel

Setze in der Compose-Datei den zuvor dokumentierten Image-Tag oder Digest wieder ein. Prüfe die Konfiguration und starte den Dienst erneut:

docker compose config --quiet
docker compose pull app
docker compose up -d --no-deps app
docker compose ps
docker compose logs --tail=100 app

Das funktioniert nur, wenn das alte Image noch verfügbar ist und die ältere Anwendung mit dem aktuellen Datenbestand umgehen kann. Verlasse dich für den Rollback nicht darauf, dass Docker ein früheres Image zufällig noch lokal gespeichert hat.

Fall 2: Das Update hat das Datenformat verändert

Viele Anwendungen führen beim Start Datenbank- oder Schema-Migrationen aus. Eine ältere Anwendungsversion kann danach möglicherweise nicht mehr mit den vorhandenen Daten arbeiten. In diesem Fall genügt es nicht, nur das alte Image einzutragen.

Stoppe die betroffenen Dienste und stelle neben der alten Compose-Konfiguration auch das vor dem Update erstellte Datenbank- und Volume-Backup wieder her. Der konkrete Restore-Befehl hängt von der Anwendung und der Art des Speichers ab. Prüfe das Verfahren möglichst vorab auf einem Testsystem. Daten, die seit dem Backup neu geschrieben wurden, können bei einem solchen Rückweg verloren gehen. Halte deshalb fest, wann die Sicherung erstellt wurde und wann das Update begonnen hat.

Diese Befehle solltest du bei Updates bewusst einsetzen

Befehl Wirkung Beim Update beachten
docker compose pull Lädt Images für die Dienste. Ersetzt laufende Container noch nicht.
docker compose up -d Startet Dienste und erstellt geänderte Container neu. Eingebundene Volumes bleiben erhalten.
docker compose restart Startet vorhandene Container neu. Übernimmt allein kein neu geladenes Image.
docker compose down Entfernt Container und Compose-Netzwerke. Für ein gewöhnliches Image-Update meist nicht nötig.
docker compose down -v Entfernt zusätzlich benannte und anonyme Volumes des Projekts. Kann dauerhaft gespeicherte Anwendungsdaten löschen.

Verwende docker compose down -v nicht als routinemäßigen „Aufräumschritt“ nach einem Update. Dasselbe gilt für ein unüberlegtes Bereinigen von Volumes oder alten Images: Erst wenn Update und möglicher Rollback abgeschlossen sind, kannst du entscheiden, welche Ressourcen nicht mehr gebraucht werden.

Häufige Probleme nach dem Aktualisieren

Der Container startet ständig neu

Sieh mit docker compose logs --tail=100 DIENSTNAME in das Protokoll des betroffenen Dienstes. Häufige Ursachen sind fehlende Umgebungsvariablen, falsche Dateirechte, ein nicht erreichbarer Datenbankdienst oder eine fehlgeschlagene Migration. Vergleiche die Release-Hinweise mit deiner aktuellen Compose-Konfiguration.

Die Anwendung ist erreichbar, aber Daten fehlen

Prüfe, ob der Dienst dasselbe Volume beziehungsweise denselben Bind-Mount wie vor dem Update verwendet. Ein geänderter Projektname kann dazu führen, dass Compose ein neues benanntes Volume anlegt. Kontrolliere auch, ob in der neuen Image-Version ein anderer Datenpfad innerhalb des Containers erwartet wird. Stoppe weitere Schreibzugriffe, bis die Ursache geklärt ist.

Das alte Image lässt sich nicht mehr laden

Ein Rollback braucht eine verfügbare, eindeutig bezeichnete Image-Version. Bei veränderlichen Tags wie latest kann pull bereits eine andere Version liefern als die ursprünglich verwendete. Dokumentiere deshalb vor Updates den bisherigen Tag oder Digest und bewahre nötige Images entsprechend deiner Betriebsstrategie auf.

Ein Dienst läuft, die Anwendung ist aber noch nicht bereit

Ein Datenbankcontainer kann bereits laufen, obwohl die Datenbank noch initialisiert wird. Ein geeigneter healthcheck und darauf abgestimmte Abhängigkeiten helfen, solche Startprobleme sichtbar zu machen. Prüfe anschließend trotzdem den eigentlichen Anwendungsablauf.

Eine kurze Update-Checkliste

  1. Aktuelle Image-Versionen und Compose-Konfiguration festhalten.
  2. Release-Hinweise und mögliche Datenmigrationen lesen.
  3. Compose-Dateien, Umgebungsdateien und Anwendungsdaten sichern.
  4. Wiederherstellungsweg für Datenbank und Volumes kennen.
  5. Neue Images mit docker compose pull laden.
  6. Dienste mit docker compose up -d aktualisieren.
  7. Status, Protokolle und wichtige Anwendungsfunktionen prüfen.
  8. Alte Image-Version und Backups bis zum Abschluss der Beobachtungsphase aufbewahren.

Fazit

Docker Compose aktualisieren ist unkompliziert, wenn du Container, Images und Daten getrennt betrachtest. pull lädt neue Images, up -d erstellt betroffene Container neu, und benannte Volumes bleiben dabei normalerweise erhalten. Für einen sicheren Rückweg brauchst du trotzdem eine bekannte alte Image-Version und ein geprüftes Backup der veränderlichen Daten.

Besonders bei Datenbankmigrationen entscheidet sich vor dem Update, wie gut ein Rollback später möglich ist. Wer Versionen dokumentiert, Backups testet und nach dem Neustart die Anwendung selbst prüft, kann Probleme deutlich gezielter beheben.

Weiterführende Docker-Dokumentation