Docker-Compose-Images kontrolliert aktualisieren¶
Veröffentlicht am 10. September 2026 · Geschätzte Lesezeit: 10 Minuten
Mit pull_policy legst du pro Compose-Dienst fest, ob Docker ein Image aus der Registry abruft oder die lokale Kopie verwendet. So verhinderst du sowohl überraschende Aktualisierungen als auch versehentlich veraltete Container.[1][4] Plane etwa 30 bis 45 Minuten für Sicherung, Anpassung und Funktionsprüfung ein.
Voraussetzungen
- Ein Linux-Server oder NAS mit Docker Engine und dem aktuellen Docker-Compose-Plugin
- Ein bereits funktionierendes Projekt mit
compose.yamloderdocker-compose.yml - Terminalzugriff auf den Projektordner und bei privaten Registrys eine bereits eingerichtete Anmeldung
- Ein aktuelles Backup der Compose-Datei und aller wichtigen Anwendungsdaten
1. Projekt, Dienste und Compose-Version prüfen¶
Wechsle in den Ordner deines vorhandenen Compose-Projekts. Ersetze <projektordner> durch dessen vollständigen Pfad:
Zeige die installierte Compose-Version an:
Prüfe danach die unveränderte Konfiguration:
Der Befehl muss ohne Fehlermeldung enden. Eine ältere Compose-Implementierung kann pull_policy oder einzelne Richtlinien noch nicht kennen. Aktualisiere in diesem Fall zuerst das offizielle Compose-Plugin für dein Betriebssystem und prüfe erneut.
Lass dir die echten Dienstnamen anzeigen:
Ein Dienstname ist der Schlüssel direkt unter services:. Er ersetzt später den Platzhalter <dienstname>.
Zeige außerdem die derzeit verwendeten Images und Container:
Notiere Image-Name, Tag, Dienstname und normalen Nutzerzugang. Diese Angaben brauchst du für den Vergleich nach der Aktualisierung.
2. Konfiguration und Anwendungsdaten sichern¶
Erstelle eine datierte Kopie der Compose-Datei. Verwendet dein Projekt compose.yaml, führe aus:
Heißt die Datei stattdessen docker-compose.yml, verwende:
Die Kopie sichert nur die Konfiguration. Sichere Datenbanken, Bind-Mounts und benannte Volumes zusätzlich mit dem dokumentierten Verfahren der jeweiligen Anwendung. Prüfe vor allem, ob das neue Image Datenbank- oder Dateiformat-Migrationen verlangt.
Speichere den aktuellen Zustand in einer lokalen Textdatei:
Die Datei hilft beim Rückweg, kann aber interne Registry-Namen enthalten. Veröffentliche sie nicht ungeprüft.
Keine Datenvolumes löschen
Verwende für ein Image-Update weder docker compose down --volumes noch docker compose down -v. Diese Optionen können benannte Volumes und damit dauerhafte Anwendungsdaten entfernen.
3. Image-Tags und Aktualisierungsziel bewerten¶
Zeige die aus der Compose-Datei aufgelösten Image-Referenzen an:
Prüfe jeden Eintrag in der Dokumentation der jeweiligen Anwendung. Ein Image-Name besteht aus einer optionalen Registry, einer optionalen Organisation, dem Image-Namen und einem Tag. Statt eines Tags kann @sha256:DIGEST auf einen unveränderlichen Inhalt zeigen.[1]
Die Platzhalter bedeuten:
REGISTRYist die Registry-Adresse, beispielsweisedocker.iooderghcr.io. Bei vielen Docker-Hub-Images entfällt dieser Teil.ORGANISATIONist der Herausgeber oder Benutzer in der Registry.IMAGEist der eigentliche Repository-Name.TAGist eine Versionsbezeichnung wie1.4.2,stableoderlatest.DIGESTist die vollständige, zuvor geprüftesha256-Kennung eines bestimmten Image-Inhalts.
Ein numerischer Tag kann trotzdem vom Herausgeber neu gesetzt werden. Ein Digest fixiert dagegen exakt einen Image-Inhalt, erhält aber nicht automatisch spätere Sicherheitsaktualisierungen. Prüfe daher immer die Veröffentlichungs- und Upgrade-Hinweise des konkreten Projekts.
Veränderliche Tags bewusst behandeln
Tags wie latest, stable, main oder edge können später auf ein anderes Image zeigen. Ein Pull kann dadurch ohne Änderung der Compose-Datei neue Software einspielen. Aktualisiere besonders Datenbanken nicht pauschal, sondern nur nach Backup und Prüfung der Migrationshinweise.
4. Passende Pull-Richtlinie auswählen¶
pull_policy wird innerhalb des betreffenden Dienstes eingetragen. Die Compose-Spezifikation definiert unter anderem diese Richtlinien:[1][4]
missing: Nur abrufen, wenn das Image nicht lokal vorhanden ist. Dies ist für Dienste ohnebuild:die normale Richtlinie. Der Taglatestist ein dokumentierter Sonderfall und wird auch beimissingabgerufen.[1][4]always: Bei einem Startvorgang immer in der Registry prüfen und das Image abrufen.[1][4]never: Nie aus der Registry abrufen; fehlt das Image lokal, schlägt der Vorgang fehl.[1][4]daily,weeklyundevery_<dauer>: Erst nach dem festgelegten Zeitraum wieder in der Registry prüfen. Ersetze<dauer>durch eine Dauer wie12h,2doder1d12h.[1][4]build: Das Image aus dem vorhandenenbuild:-Abschnitt bauen, auch wenn es lokal bereits vorhanden ist.[1][4]
Für einen kleinen produktiven Heimserver ist eine vorsichtige Ausgangsbasis:
- Verwende
missingbei getesteten festen Versionstags und führe Updates ausdrücklich aus. - Verwende
alwaysnur bei einem bewusst veränderlichen Tag, dessen neue Version bei jedem Start gewünscht ist. - Verwende
nevernur für ein nachweislich lokal vorhandenes oder offline bereitgestelltes Image. - Behandle Dienste mit
build:getrennt; diese Anleitung konzentriert sich auf veröffentlichte Registry-Images.
Die Praxisanleitung von Lours beschreibt dieselben Richtlinien und zeigt zusätzlich zeitgesteuerte Varianten sowie CLI-Überschreibungen.[5] Für das genaue Verhalten bleibt die aktuelle Compose-Spezifikation maßgeblich.[1][4]
5. pull_policy in der Compose-Datei eintragen¶
Öffne die vorhandene Datei:
Bei docker-compose.yml ersetzt du den Dateinamen entsprechend. Ergänze bei einem bereits vorhandenen Dienst beispielsweise missing:
services:
app:
image: <registry>/<organisation>/<image>:<tag>
pull_policy: missing
restart: unless-stopped
Übernimm nicht den gesamten Block blind, sondern ergänze nur pull_policy beim richtigen Dienst und behalte dessen bisherige Optionen bei. Die Werte bedeuten:
appist ein Beispiel-Dienstname. Ersetze ihn durch den vorhandenen Namen unterservices:.- Ersetze
<registry>durch die echte Registry-Adresse ohne Protokollpräfix. - Ersetze
<organisation>durch den Herausgeber oder Registry-Benutzer. - Ersetze
<image>durch den Repository-Namen. - Ersetze
<tag>durch den bewusst gewählten und zuvor geprüften Image-Tag. missingverwendet die lokale Kopie, solange das Image vorhanden ist;latestbleibt der dokumentierte Sonderfall.[1][4]restart: unless-stoppedist nur Kontext. Ändere eine vorhandene Restart-Richtlinie nicht wegen dieses Beispiels.
Wenn ein veränderlicher Tag bei jedem Start geprüft werden soll, lautet nur die betreffende Zeile anders:
Für einen absichtlich offline betriebenen Dienst kannst du nach Prüfung des lokalen Images verwenden:
never ist keine Backup- oder Sicherheitsfunktion. Ist das angegebene Image nicht im lokalen Cache, meldet Compose einen Fehler.[1][4]
6. Geänderte Konfiguration vor dem Pull validieren¶
Prüfe die YAML-Datei und das aufgelöste Compose-Modell:
Zeige danach noch einmal Dienste und Images:
Kontrolliere, ob der beabsichtigte Dienst weiterhin denselben Image-Namen und Tag verwendet. pull_policy entscheidet nur, wann Compose abruft; die Richtlinie ersetzt keine passende Versionsauswahl.
Aufgelöste Konfiguration vertraulich behandeln
Eine vollständige Ausgabe von docker compose config kann interpolierte Umgebungswerte zeigen. Kopiere sie nicht ungeprüft in Foren, Tickets oder öffentliche Repositorys.
7. Einen Dienst kontrolliert aktualisieren¶
Wähle zuerst einen unkritischen Dienst. Ersetze <dienstname> durch den echten Namen aus docker compose config --services:
docker compose pull lädt das zum Dienst gehörende Image, startet aber noch keinen Container.[2] Bei einem unveränderten Image müssen nicht alle Layer erneut geladen werden.
Übernimm das bereitgestellte Image anschließend nur für diesen Dienst:
--no-deps verhindert, dass Compose gleichzeitig abhängige Dienste startet oder neu erstellt. Verwende die Option nur, wenn der gewählte Dienst allein aktualisiert werden darf. Bei eng gekoppelten Anwendungs- und Datenbankdiensten folgst du stattdessen der offiziellen Update-Reihenfolge des Projekts.
Alternativ erzwingst du den Pull einmalig beim Start, ohne die Datei zu ändern:
Die Option --pull always weist docker compose up für diesen Lauf an, das Image vor dem Start abzurufen; up erstellt geänderte Container neu und startet sie.[3] Diese einmalige Option ersetzt keine dokumentierte dauerhafte Richtlinie in der Compose-Datei.
Kurze Unterbrechung einplanen
Wenn sich das Image geändert hat, kann Compose den Container neu erstellen. Plane bei produktiven Diensten ein Wartungsfenster ein und beende vorher wichtige Schreibvorgänge nach der Anwendungsdokumentation.
8. Neues Image und Anwendung prüfen¶
Kontrolliere den Containerzustand:
Zeige das vom Projekt verwendete Image:
Lies anschließend die letzten Protokollzeilen:
Ersetze <dienstname> in allen drei Befehlen durch denselben echten Compose-Dienstnamen. Prüfe die Logs auf Startfehler, Migrationen und wiederholte Neustarts. Veröffentliche keine Ausgabe, die Tokens, Benutzernamen oder interne Adressen enthält.
Teste danach den echten Nutzerweg: Öffne die Weboberfläche oder den Client, melde dich an und führe eine ungefährliche Lese- und Schreibprobe aus. Bei einem Dienst mit Healthcheck sollte der Status zusätzlich healthy werden. Ein lediglich laufender Container beweist noch nicht, dass die Anwendung funktioniert.
Das öffentlich auffindbare Video „Update Docker Images: A Beginner's Guide to Keep Your Containers Fresh!“ zeigt das allgemeine Aktualisieren von Docker-Images und Compose-Containern ergänzend.[7] Für die Semantik von pull_policy und den CLI-Optionen sind die offiziellen Referenzen maßgeblich.[1][2][3]
9. Risiken und typische Fehler beheben¶
Beachte diese Grenzen:
pull_policy: alwayskann bei jedem passenden Compose-Lauf Registry-Zugriffe auslösen. Bei einem Ausfall der Registry kann der Start oder die Aktualisierung scheitern.pull_policy: missinggarantiert nicht die neueste Veröffentlichung. Beilatestgilt außerdem der dokumentierte Sonderfall, dass Compose trotzdem abruft.[1][4]- Ein Pull ändert keine laufenden Container. Erst ein anschließendes
docker compose up -dübernimmt ein neues Image.[2][3] - Ein Downgrade kann nach einer Datenmigration unmöglich oder nur aus einem Backup möglich sein.
- Ein Image-Update ersetzt weder Sicherheitsprüfung noch Backup, Wartungsfenster und Funktionstest.
- Lösche alte Images nicht, bevor die neue Version geprüft und der Rückweg gesichert ist.
Typische Fehler lassen sich so eingrenzen:
pull_policywird als unbekannt gemeldet: Prüfedocker compose versionund aktualisiere das Compose-Plugin. Verwende nicht versehentlich das alte Programmdocker-composemit Bindestrich.- Falscher Dienstname: Führe
docker compose config --servicesaus und übernimm die Schreibweise exakt. - Image wird trotz
missingabgerufen: Prüfe, ob es lokal wirklich unter derselben vollständigen Referenz vorhanden ist. Beachte den Sonderfalllatest.[1][4] neverschlägt sofort fehl: Das angegebene Image fehlt lokal. Lade es bewusst vor oder ändere die Richtlinie nach Prüfung.- Privates Image kann nicht geladen werden: Prüfe Registry-Adresse und vorhandene Anmeldung. Schreibe Kennwörter oder Tokens nicht in die Compose-Datei oder Befehlszeile.
- Container verwendet weiterhin die alte Version: Führe nach dem Pull
docker compose up -d <dienstname>aus und kontrollieredocker compose images <dienstname>.[2][3] - Anwendung startet, funktioniert aber nicht: Lies die Dienstlogs, prüfe die Herstellerhinweise zur Zielversion und stelle bei Bedarf die vorherige Konfiguration sowie das Datenbackup wieder her.
- Falsches Projekt wird geändert: Prüfe den aktuellen Ordner und die dort liegende Compose-Datei, bevor du einen Pull oder ein
upausführst.
10. Rückweg sicher durchführen¶
Zeige zuerst die angelegte Sicherung an:
Bei einer ursprünglichen docker-compose.yml verwendest du:
Ersetze <sicherungsdatei> durch den vollständigen Namen der gewünschten, zuvor angelegten Sicherung. Für compose.yaml lautet der Rückkopierbefehl:
Für docker-compose.yml lautet er:
Prüfe die wiederhergestellte Konfiguration:
Zeigt die Sicherung wieder auf einen früheren Tag oder Digest, rufe dieses Image bewusst ab:
Übernimm danach nur den betroffenen Dienst:
Kontrolliere anschließend Status, Image, Logs und den normalen Nutzerzugang. Ein alter veränderlicher Tag kann inzwischen auf ein anderes Image zeigen. Ein wirklich reproduzierbarer Rückweg braucht daher einen dokumentierten früheren Digest oder ein gesichertes Image. Hat die neue Version Daten migriert, stelle zusätzlich das vor dem Update erstellte Anwendungsbackup nach der offiziellen Projektdokumentation wieder her.
Sources¶
[1] https://docs.docker.com/reference/compose-file/services.md — Docker Docs: Define services in Docker Compose [2] https://docs.docker.com/reference/cli/docker/compose/pull.md — Docker Docs: docker compose pull [3] https://docs.docker.com/reference/cli/docker/compose/up.md — Docker Docs: docker compose up [4] https://compose-spec.github.io/compose-spec/05-services.html — Compose Specification: Services [5] https://lours.me/posts/compose-tip-067-pull-policy — Docker Compose Tip #67: Controlling image pulls with pull_policy [7] https://www.youtube.com/watch?v=mwoWu6cLsfU — YouTube: Update Docker Images – A Beginner's Guide
Fertig¶
Dein Compose-Projekt verwendet jetzt eine bewusste Pull-Richtlinie statt eines zufälligen Aktualisierungsverhaltens. Die Funktionsprüfung ist bestanden, wenn docker compose config --quiet ohne Fehler endet, docker compose pull <dienstname> erfolgreich läuft, docker compose up -d --no-deps <dienstname> den gewünschten Container startet, docker compose images <dienstname> das erwartete Image zeigt, die Logs keine neuen Fehler enthalten und der normale Nutzerweg funktioniert.[1][2][3]