Docker Compose Watch: Hot-Reload für Dev-Container im Homelab

Wer im Homelab mit Docker entwickelt, kennt das Problem: Jede kleine Code-Änderung erfordert einen docker compose build gefolgt von docker compose up -d. Das kostet Zeit, unterbricht den Flow und macht schnelles Iterieren fast unmöglich. Die Lösung heißt Docker Compose Watch – ein mächtiges Feature, das viele Homelaber noch nicht auf dem Radar haben.

Was ist Docker Compose Watch?

Seit Docker Compose v2.22 gibt es das docker compose watch Kommando. Es überwacht Dateiänderungen im Host-Verzeichnis und synchronisiert sie automatisch in den laufenden Container – ohne Neustart des gesamten Stacks. Anders als klassisches Volume-Mounting ist Watch intelligent: Es kann bestimmte Dateien oder Verzeichnisse gezielt synchronisieren und Aktionen wie sync, rebuild oder restart auslösen.

Der entscheidende Unterschied zu Volumes

Ein normaler Bind-Mount (./app:/app) gibt dem Container direkten Zugriff auf das Host-Dateisystem. Das klingt praktisch, hat aber Nachteile: Performance-Einbußen bei vielen Dateien, fehlende Kontrolle über was synchronisiert wird, und bei Node.js/Python-Probleme mit node_modules oder venvs, die plötzlich im Container landen.

Docker Compose Watch löscht diese Probleme elegant: Du definierst genau, welche Pfade synchronisiert werden und ob bei Änderungen ein Rebuild oder Restart erfolgen soll. Das spart Zeit und macht den Entwicklungsprozess sauberer.

So richtest du Watch ein

Die Konfiguration erfolgt direkt in der compose.yaml unter dem neuen Schlüssel develop. Hier ein minimales Beispiel für einen Python/FastAPI-Service mit Hot-Reload:

services:
  api:
    build: .
    ports:
      - "8000:8000"
    command: uvicorn app.main:app --reload --host 0.0.0.0
    develop:
      watch:
        - action: sync
          path: ./app
          target: /app
          ignore:
            - .venv/
            - __pycache__/
        - action: rebuild
          path: ./requirements.txt

Der Watch-Teil definiert zwei Regeln:

• sync – Änderungen an Python-Dateien in ./app werden direkt in den Container synchronisiert. Der Uvicorn --reload-Flag startet den Server automatisch neu.
• rebuild – Wird die requirements.txt geändert (neue Abhängigkeit), baut Docker das Image komplett neu und startet den Service.

Gestartet wird der ganze Zauber mit einem einfachen Befehl:

docker compose watch

Der Container läuft, und Watch bleibt im Vordergrund aktiv. Ab jetzt werden alle Änderungen sofort im Container sichtbar – kein manuelles Neustarten mehr.

Praktische Beispiele fürs Homelab

Webentwicklung mit Node.js

Für Next.js, Astro oder Vite-Projekte siehst du Änderungen in Echtzeit, ohne dass der Dev-Server im Container jedes Mal neustarten muss:

services:
  frontend:
    build: ./frontend
    ports:
      - "3000:3000"
    develop:
      watch:
        - action: sync
          path: ./frontend/src
          target: /app/src
        - action: sync
          path: ./frontend/public
          target: /app/public

Go-Backend mit Air

Go-Entwickler nutzen oft Air oder ähnliche Live-Reload-Tools. Kombiniert mit Watch wird selbst das Compile-Step automatisiert:

services:
  backend:
    build: .
    develop:
      watch:
        - action: sync
          path: ./
          target: /app

Warum Watch perfekt fürs Homelab ist

Im Homelab entwickeln wir oft auf dem gleichen Rechner, auf dem die Container laufen – da bietet sich Watch geradezu an. Die Vorteile im Überblick:

• Weniger Builds – Nur bei relevanten Änderungen (neue Dependencies, Dockerfile-Änderungen) wird tatsächlich gebaut
• Schnelleres Feedback – Code speichern und sofort im Browser oder API-Client testen
• Ressourcenschonend – Kein ständiges Neu-Starten des Docker-Stacks, weniger CPU-Last
• Kontrollierte Synchronisation – Nur die wichtigen Pfade werden überwacht, Cache- und Build-Ordner ignoriert
• Klarer Entwicklungs-Workflow – Was im Container passiert, bleibt im Container. Kein Mix aus Host- und Container-Umgebungen

Tipps aus der Praxis

1. Ignore-Regeln nicht vergessen – node_modules, .venv, __pycache__ und .git sollten immer auf der Ignore-Liste stehen, sonst wird die Synchronisation langsam.
2. Achtung bei Symlinks – Watch folgt standardmäßig keinen Symlinks. Werden sie benötigt, muss das explizit konfiguriert werden.
3. Kombination mit --reload – Die Sprache/ das Framework muss den Server-Hot-Reload unterstützen (Uvicorn, Nodemon, Air, Nodemon). Watch synchronisiert nur die Dateien – den Neustart macht das Tool im Container.
4. Log-Ausgabe im Watch-Modus – docker compose watch zeigt live an, welche Dateien synchronisiert werden. Bei Problemen hilft ein Blick in diese Logs.
5. Watch nur für Entwicklung – In Produktion wird natürlich das fertige Image verwendet. Watch ist ein reines Dev-Tool.

Fazit

Docker Compose Watch ist eines dieser Features, das die tägliche Arbeit im Homelab spürbar angenehmer macht. Es ist leichtgewichtig, einfach konfiguriert und beseitigt genau den Frust, der beim ständigen manuellen Neustarten von Containern entsteht. Wer regelmäßig Docker-basierte Projekte entwickelt, sollte Watch definitiv eine Chance geben.

Hast du Docker Compose Watch schon ausprobiert? Welche Erfahrungen hast du damit gemacht? Schreib es in die Kommentare oder teile deine Konfiguration – ich bin gespannt!

🎯 Empfehlung: Nextcloud Performance: Redis & APCu Cache richtig einstellen – Auch die Nextcloud-Infrastruktur profitiert von gut konfigurierten Caches – Redis und APCu machen den Unterschied.

🎯 Empfehlung: Prometheus & Grafana: Docker-Monitoring im Homelab selbst hosten – Sobald deine Container laufen, willst du sie überwachen – Prometheus & Grafana sind der Goldstandard für Docker-Monitoring.

🔗 Neu: Docker Container selbstheilend machen: HEALTHCHECK, Restart-Policies & Watchtower – Ergnzend zu Healthchecks und Restart-Policies hilft Docker Compose Watch bei Entwicklungsworkflows.