Zum Inhalt

Docker Compose Watch für schnellere Entwicklungsabläufe einrichten

Veröffentlicht am 31. August 2026 · Geschätzte Lesezeit: 7 Minuten

Docker Compose Watch übernimmt lokale Dateiänderungen automatisch in einen laufenden Entwicklungscontainer oder baut den betroffenen Dienst gezielt neu. So entfällt bei vielen Änderungen das manuelle Stoppen, Bauen und Starten. Die Einrichtung dauert etwa 20 bis 40 Minuten und ist ausschließlich für lokale Entwicklung und Tests gedacht.

Voraussetzungen

  • Docker Engine mit dem Docker-Compose-Plugin ab Version 2.22.0
  • Ein funktionierendes Compose-Projekt mit einem Dienst, der über build: aus lokalem Quellcode gebaut wird
  • Ein Quellordner src, auf den der Benutzer im Container schreiben darf
  • Ein aktuelles Backup der Compose-Datei und aller wichtigen Projektdaten

1. Projekt und Compose-Datei sichern

Wechsle in den vorhandenen Projektordner. Ersetze <projektordner> durch den vollständigen Pfad zu deinem Compose-Projekt:

cd <projektordner>

Prüfe zuerst den aktuellen Zustand der Dienste:

docker compose ps

Erstelle anschließend eine datierte Sicherung der Compose-Datei:

cp compose.yaml "compose.yaml.vor-watch-$(date +%F-%H%M)"

Verwendet dein Projekt stattdessen docker-compose.yml, musst du in allen Sicherungs- und Rückweg-Befehlen diesen Dateinamen einsetzen. Die Dateikopie schützt nur die Konfiguration; sichere Datenbanken und Anwendungsdaten weiterhin mit dem Verfahren der jeweiligen Anwendung.

2. Docker-Compose-Version und Projekt prüfen

Zeige die installierte Compose-Version an:

docker compose version

Der optionale develop-Abschnitt steht laut Compose-Spezifikation ab Docker Compose 2.22.0 zur Verfügung.[2] Ist deine Version älter, aktualisiere das Compose-Plugin über die offizielle Paketquelle deines Systems, bevor du fortfährst.

Lass danach die unveränderte Konfiguration vollständig auflösen:

docker compose config

Der Befehl muss ohne Syntax- oder Variablenfehler enden. Compose Watch ist für Dienste gedacht, die mit build: aus lokalem Quellcode entstehen; reine Dienste mit einem vorgefertigten image: werden nicht auf diese Weise überwacht.[1]

3. Watch-Regeln ergänzen

Öffne die vorhandene compose.yaml und ergänze im Entwicklungsdienst den Abschnitt develop.watch. Das folgende Beispiel geht von einer Node.js-Anwendung mit dem lokalen Ordner src, dem Arbeitsordner /app im Image und einem Entwicklungsserver auf Port 5173 aus:

services:
  web:
    build: .
    command: npm run dev
    ports:
      - "${APP_PORT:-5173}:5173"
    develop:
      watch:
        - action: sync
          path: ./src
          target: /app/src
          initial_sync: true
          ignore:
            - node_modules/

        - action: rebuild
          path: ./package.json

        - action: rebuild
          path: ./package-lock.json

Passe den Block an dein vorhandenes Projekt an:

  • web ist der Compose-Dienstname und wird in den späteren Befehlen verwendet.
  • build: . verweist auf den Ordner mit dem vorhandenen Dockerfile.
  • npm run dev muss zu deinem tatsächlichen Entwicklungsbefehl passen und selbst Hot Reload oder einen Datei-Watcher unterstützen.
  • ${APP_PORT:-5173} verwendet den Wert der Umgebungsvariablen APP_PORT oder ersatzweise Host-Port 5173. Der rechte Port 5173 muss dem Port des Entwicklungsservers im Container entsprechen.
  • ./src ist der lokale Quellordner. /app/src ist der zugehörige Zielordner im Container und muss zum Arbeitsverzeichnis deines Images passen.
  • initial_sync: true gleicht beim Start bereits vorhandene Dateien ab.
  • ignore ist relativ zum jeweiligen path; ausgeschlossene Verzeichnisse werden nicht synchronisiert.[1]
  • Änderungen an package.json oder package-lock.json lösen einen Image-Neubau aus, weil sich dadurch installierte Abhängigkeiten ändern können.

Bei sync bleibt der Container bestehen und Compose kopiert geänderte Dateien zum Ziel. rebuild baut dagegen das Image neu und erstellt den Dienst mit diesem Image erneut.[2]

Nur notwendige Ordner überwachen

Verwende nicht unüberlegt path: .. Schließe Geheimnisse, .env-Dateien, private Schlüssel, .git, virtuelle Python-Umgebungen, Build-Ausgaben und Host-Abhängigkeiten aus. Ein eng gefasster src-Pfad verhindert unbeabsichtigte Kopien und unnötige Neubauten.

4. Schreibrechte im Container sicherstellen

Compose Watch benötigt im Image die Programme stat, mkdir und rmdir. Außerdem muss der konfigurierte Container-Benutzer in den Zielordner schreiben dürfen.[1] Prüfe zunächst den Benutzer und den Zielordner des bereits laufenden Dienstes:

docker compose exec web sh -c 'id && ls -ld /app /app/src'

Passe web, /app und /app/src an, falls dein Dienst oder Arbeitsordner anders heißt. Meldet der Test fehlende Schreibrechte, korrigiere nicht pauschal mit chmod 777. Lege den Ordner stattdessen beim Image-Bau an und übertrage die Dateien an den unprivilegierten Anwendungsbenutzer, zum Beispiel so:

WORKDIR /app
COPY --chown=app:app ./src /app/src
USER app

app:app steht hier für Benutzer und Gruppe deines vorhandenen Images. Sind sie dort anders benannt, musst du beide Werte anpassen. Das Beispiel setzt voraus, dass der Benutzer bereits im Dockerfile oder Basis-Image existiert.

5. Aufgelöste Watch-Konfiguration kontrollieren

Prüfe nach der Änderung erneut die gesamte Compose-Datei:

docker compose config

Kontrolliere in der Ausgabe besonders den Dienst web, die Quellpfade unter path und die Containerpfade unter target. Ein falscher Zielpfad kann Dateien erfolgreich kopieren, ohne dass die Anwendung sie verwendet.

6. Dienst und Überwachung starten

Starte oder aktualisiere zunächst den Entwicklungsdienst im Hintergrund:

docker compose up -d --build web

Öffne danach ein zweites Terminal im selben Projektordner und starte die Überwachung im Vordergrund:

docker compose watch web

Der Befehl kann einen oder mehrere Dienstnamen überwachen und zeigt Synchronisierungen sowie Neubauten direkt an.[3] Beende die Überwachung später mit Strg+C. Prüfe die Container danach separat mit docker compose ps; das Beenden des Vordergrundbefehls ist kein Ersatz für docker compose down.

Alternativ kann docker compose up --watch Start, Logs und Überwachung in einem Vordergrundprozess verbinden.[1]

7. Synchronisierung praktisch testen

Lege im lokalen Quellordner eine harmlose Testdatei an:

touch src/watch-test.txt

Beobachte im Watch-Terminal, ob Compose eine Synchronisierung meldet. Prüfe anschließend im zweiten Terminal, ob die Datei im Container angekommen ist:

docker compose exec web test -f /app/src/watch-test.txt

Der Befehl endet ohne Ausgabe und mit Exit-Code 0, wenn die Datei vorhanden ist. Zeige den Exit-Code direkt danach an:

printf 'Exit-Code: %s\n' "$?"

Entferne die Testdatei wieder und kontrolliere, ob auch die Löschung übernommen wird:

rm src/watch-test.txt

docker compose exec web test ! -e /app/src/watch-test.txt

Prüfe zusätzlich die Anwendung im Browser über den von APP_PORT festgelegten Host-Port. Ändere eine sichtbare Textstelle unter src und bestätige, dass der Entwicklungsserver die Änderung ohne manuellen Container-Neustart übernimmt. sync kopiert nur Dateien; Hot Reload muss der Prozess im Container selbst bereitstellen.[1][4]

8. Konfigurationsänderungen mit Neustart übernehmen

Liest deine Anwendung eine Konfigurationsdatei nur beim Start, kann sync+restart statt sync sinnvoll sein. Ergänze dafür eine eng begrenzte Regel:

services:
  web:
    develop:
      watch:
        - action: sync+restart
          path: ./config/app.conf
          target: /app/config/app.conf

Hier stehen ./config/app.conf und /app/config/app.conf für die tatsächliche Konfigurationsdatei auf dem Host und im Container; beide Pfade musst du an dein Projekt anpassen. sync+restart synchronisiert die Datei und startet anschließend den Container neu. Diese Aktion ist ab Docker Compose 2.23.0 verfügbar.[2]

Warning

Überwache keine produktiven Konfigurationsdateien und keine Dateien mit Kennwörtern oder Tokens. Compose Watch ist ein Entwicklungswerkzeug und kein Verfahren für Deployments auf Produktivservern.

9. Backup und Rückweg verwenden

Beende zuerst die laufende Überwachung mit Strg+C. Suche danach den Namen deiner Sicherungsdatei:

ls -1 compose.yaml.vor-watch-*

Kopiere die gewünschte Sicherung zurück. Ersetze <sicherungsdatei> durch den vollständigen Dateinamen aus der vorherigen Ausgabe:

cp <sicherungsdatei> compose.yaml

Prüfe die wiederhergestellte Konfiguration:

docker compose config

Erstelle den betroffenen Dienst mit der alten Konfiguration neu:

docker compose up -d --build web

Soll der gesamte Entwicklungsstack beendet werden, verwende anschließend diesen Befehl:

docker compose down

Verwende nicht docker compose down -v, weil -v zusätzlich benannte Volumes entfernt.

10. Typische Fehler beheben

  • watch ist kein bekannter Befehl: Prüfe mit docker compose version, ob mindestens Version 2.22.0 installiert ist und ob du docker compose mit Leerzeichen statt des alten Befehls docker-compose verwendest.[2][4]
  • Die Datei wird nicht kopiert: Kontrolliere, ob docker compose watch web noch läuft, der lokale path stimmt und keine ignore-Regel die Datei ausschließt.
  • permission denied erscheint: Prüfe mit docker compose exec web sh -c 'id && ls -ld /app/src' Benutzer und Zielrechte. Korrigiere Besitzer und Gruppe beim Image-Bau statt mit globalen Schreibrechten.
  • Die Datei ist vorhanden, aber die Anwendung reagiert nicht: Der Entwicklungsprozess muss Hot Reload unterstützen. Verwende sonst für passende Konfigurationen sync+restart oder für Abhängigkeitsänderungen rebuild.
  • Bei jedem Speichern wird neu gebaut: Begrenze rebuild auf Manifest- und Lock-Dateien. Nutze für normalen Quellcode sync.[4]
  • Änderungen landen im falschen Containerpfad: Vergleiche den aufgelösten target aus docker compose config mit dem Arbeits- und Quellpfad deiner Anwendung.
  • Auf einem entfernten Docker-Kontext werden falsche Dateien übertragen: Prüfe vor dem Start mit docker context show, welcher Docker-Host aktiv ist. Starte Watch nur für den ausdrücklich vorgesehenen Entwicklungsrechner.

Grundlage dieser Anleitung sind die aktuelle offizielle Docker-Anleitung zu Compose Watch und die Compose-Develop-Spezifikation, geprüft am 31. August 2026. Als ergänzende Praxisquellen dienen die Anleitung von Stack Harbor und das öffentlich auffindbare Video „Docker Compose Watch: Hot Reload & Rebuild Explained“.[4][6]

Sources

[1] https://docs.docker.com/compose/how-tos/file-watch — Use Compose Watch [2] https://docs.docker.com/reference/compose-file/develop — Compose Develop Specification [3] https://docs.docker.com/reference/cli/docker/compose/watch — docker compose watch [4] https://stackharbor.com/en/knowledge-base/docker-compose-watch-live-reload — Docker Compose watch: live-reload your app inside containers [6] https://www.youtube.com/watch?v=FhorvGysZ6w — Docker Compose Watch: Hot Reload & Rebuild Explained (2025 Tutorial)

Fertig

Docker Compose überwacht jetzt die ausgewählten Entwicklungsdateien und führt je nach Regel eine Synchronisierung, einen Neustart oder einen Neubau aus. Die Funktionsprüfung ist erfolgreich, wenn docker compose config ohne Fehler endet, docker compose watch web Änderungen meldet, der Test mit test -f Exit-Code 0 liefert und eine sichtbare Quelltextänderung vom Entwicklungsserver übernommen wird.