Po zmianie jednego pliku nie zawsze trzeba ręcznie przebudowywać obraz i uruchamiać aplikację od początku. Docker Compose Watch może wykryć zapis, skopiować plik do kontenera albo zbudować nowy obraz. Kluczowy jest wybór właściwej akcji: synchronizacja plików nie oznacza automatycznie restartu procesu.
W tym poradniku uruchomisz małą stronę w kontenerze i sprawdzisz dwa scenariusze: zmianę HTML bez wymiany kontenera oraz zmianę Dockerfile z przebudową. To środowisko programistyczne, a nie procedura wdrażania produkcji.
Co robi Compose Watch
Watch obserwuje wybrane ścieżki projektu i reaguje według reguł develop.watch. Usługę budujesz z lokalnego kodu przez build. Zwykłe pobranie gotowego obrazu przez samo image nie tworzy projektu źródłowego, którego zmiany Watch miałby obsługiwać. Wymagania opisuje instrukcja Compose Watch.
To mechanizm przydatny, gdy wielokrotnie powtarzasz cykl: edycja, uruchomienie, sprawdzenie wyniku. Nie zastępuje kontroli wersji, testów ani budowania artefaktu do wydania. Jeśli dopiero poznajesz kontenery, zacznij od podstaw działania Dockera.
Synchronizacja, restart i przebudowa
| Akcja | Co się zmienia | Typowe zastosowanie |
|---|---|---|
sync |
Pliki w istniejącym kontenerze | Kod odczytywany na bieżąco lub przez reloader aplikacji |
sync+restart |
Pliki, potem restart kontenera | Konfiguracja odczytywana przy starcie procesu |
rebuild |
Obraz i odtworzony kontener usługi | Zależności, instrukcje budowania, kod wymagający kompilacji |

Sekcja develop jest dostępna od Compose 2.22.0, a sync+restart od 2.23.0. Nowsze wydania mają również inne akcje, lecz nie potrzebujesz ich do tego przykładu. Szczegóły i progi wersji znajdują się w Compose Develop Specification.
Sprawdź zainstalowane narzędzie poleceniem docker compose version. Używamy polecenia z odstępem, czyli aktualnego pluginu Compose, nie historycznego docker-compose. Przykład zweryfikowano na Compose v5.1.3; nie jest to minimalna wymagana wersja.
Przygotuj mały projekt
Utwórz katalog z plikami compose.yaml, Dockerfile, .dockerignore oraz podkatalogiem site, zawierającym index.html. Polecenia uruchamiaj w katalogu projektu. Docker Engine musi działać i być dostępny dla twojego użytkownika.
Plik strony
W site/index.html zapisz:
<!doctype html>
<html lang="pl">
<meta charset="utf-8">
<title>Compose Watch</title>
<h1>Wersja pierwsza</h1>
</html>
Dockerfile
FROM python:3.13-alpine
RUN adduser -D app
WORKDIR /app
COPY --chown=app:app site/ ./site/
USER app
CMD ["python", "-m", "http.server", "8000", "--bind", "0.0.0.0", "--directory", "/app/site"]
Kontener działa jako użytkownik app. COPY --chown przekazuje mu własność plików, aby Watch mógł je aktualizować. Obraz musi również zawierać narzędzia stat, mkdir i rmdir potrzebne do synchronizacji. Wybrany obraz Alpine spełnił te wymagania w teście.
Python służy tutaj tylko do udostępnienia pliku demonstracyjnego. Jego wbudowany serwer HTTP nie jest zalecany na produkcję. Parametr 0.0.0.0 dotyczy nasłuchu wewnątrz kontenera; zasięg dostępu na hoście ograniczymy osobno.
Tag python:3.13-alpine może wskazywać z czasem nowszy wariant obrazu. Dla powtarzalnego wydania można przypiąć digest i świadomie go aktualizować. Znaczenie wersjonowania obrazu oraz kolejności warstw opisują dobre praktyki budowania obrazów.
compose.yaml
services:
web:
build: .
ports:
- "127.0.0.1:8000:8000"
develop:
watch:
- action: sync
path: ./site
target: /app/site
- action: rebuild
path: ./Dockerfile
Mapowanie 127.0.0.1:8000:8000 udostępnia stronę na lokalnym interfejsie hosta Docker. Jeśli Docker działa na zdalnym serwerze, 127.0.0.1 oznacza tamten serwer, a nie twój laptop. Składnię publikowania portów opisuje referencja usług Compose.
Pierwsza reguła obserwuje katalog site. Zmiana site/index.html trafia do /app/site/index.html. Druga obserwuje Dockerfile i wybiera pełną przebudowę. Nie używamy jednocześnie bind mounta na /app/site, ponieważ zaciemniłoby to mechanizm testu.

.dockerignore
.git
.env
__pycache__
*.log
Ten plik ogranicza zawartość kontekstu budowania. Jego reguły wpływają też na obserwowanie plików. Szczegóły dopasowywania wzorców zawiera dokumentacja kontekstu i .dockerignore.
W większym projekcie wyklucz lokalne środowiska, katalogi zależności i sekrety. Nie kopiuj node_modules z Windows do kontenera Linux: część pakietów zawiera komponenty zależne od platformy. Zależności instaluj wewnątrz procesu budowania odpowiedniego obrazu.
Uruchom Watch i zmień stronę
Najpierw sprawdź konfigurację, potem uruchom usługę:
docker compose config -q
docker compose up --watch
Otwórz http://127.0.0.1:8000. Zostaw terminal z Compose uruchomiony. Zmień tekst nagłówka w HTML na Wersja druga, zapisz plik i odśwież przeglądarkę. Watch powinien zsynchronizować plik bez przebudowy obrazu.
Automatyczne kopiowanie nie oznacza automatycznego odświeżania karty. W tym przykładzie odświeżasz ją sam. Framework może mieć własny hot reload, ale jest to dodatkowy mechanizm aplikacji, działający po otrzymaniu zmienionych plików.

W drugim terminalu możesz sprawdzić identyfikator kontenera przed i po zmianie:
docker compose ps -q web
Przy sync powinien pozostać ten sam. Samo zobaczenie nowej treści nie rozróżnia synchronizacji od odtworzenia usługi, dlatego warto sprawdzić oba objawy.
Wywołaj przebudowę obrazu
Dopisz do Dockerfile instrukcję:
LABEL demo.version="2"
To nie zmienia wyglądu strony, ale zmienia instrukcje obrazu. Reguła rebuild powinna uruchomić build i odtworzyć usługę. Zobaczysz komunikaty w terminalu oraz nowy identyfikator kontenera. Jeśli build się nie powiedzie, przeczytaj pierwszy konkretny błąd zamiast zakładać, że Watch nie zauważył pliku.
W aplikacji z zależnościami podobna reguła może obserwować requirements.txt, package.json lub plik blokady wersji. Musi to odpowiadać Dockerfile: samo wykrycie zmiany nie zainstaluje zależności, jeśli obraz nie zawiera odpowiedniej instrukcji instalacji.
Układaj warstwy tak, by zmiana kodu nie wymuszała zbędnego pobierania wszystkich pakietów. To sposób organizacji budowania, a nie specjalne przyspieszenie gwarantowane przez Watch. Duży kontekst, pobieranie z sieci i kompilacja nadal kosztują czas.
Co sprawdzić, gdy zmiany nie działają
Zacznij od trzech pytań: czy wykryto plik, czy trafił do właściwego miejsca, czy aplikacja go ponownie odczytała? To osobne etapy, które łatwo pomylić.
| Objaw | Pierwsza rzecz do sprawdzenia |
|---|---|
| Brak reakcji w terminalu | Czy działa Watch i czy ścieżka nie jest ignorowana |
| Plik nie pojawia się w kontenerze | path, target, prawa zapisu użytkownika |
| Plik jest nowy, odpowiedź stara | Cache przeglądarki lub brak reloadu procesu aplikacji |
| Każda drobna zmiana uruchamia build | Zbyt szeroka reguła rebuild |
| Zmiana zależności nic nie daje | Czy obserwujesz właściwy manifest i lockfile |
W przykładzie treść pliku sprawdzisz poleceniem docker compose exec web cat /app/site/index.html. To pozwala oddzielić błąd synchronizacji od problemu przeglądarki. Jeśli zmieniasz konfigurację odczytywaną tylko przy starcie, samo sync może działać poprawnie, lecz nie wystarczać aplikacji.
Po zmianie samych reguł Watch zatrzymaj i uruchom obserwowanie ponownie. Gdy chcesz mieć osobny terminal z logami aplikacji, możesz użyć dedykowanego docker compose watch. Aktualne opcje, w tym --no-up, opisuje referencja polecenia watch.
Pracuj na plikach źródłowych hosta. Zmiany wykonane ręcznie wewnątrz kontenera nie są wygodnym sposobem rozwijania projektu i mogą zniknąć po odtworzeniu usługi. Obraz pozostaje odrębnym artefaktem od roboczych plików zsynchronizowanych do kontenera.
Zakończenie pracy i granica produkcji
Po zakończeniu sesji zatrzymaj Watch przez Ctrl+C, a zasoby przykładu usuń przez docker compose down w jego katalogu. Nie uruchamiaj ogólnego czyszczenia wszystkich zasobów Docker tylko po to, aby zamknąć jeden projekt.
Na serwerze obsługującym użytkowników wdrażaj przetestowany obraz i kontroluj moment zmiany. Watch jest wygodny do programowania, lecz zapis przypadkowego pliku nie powinien stanowić procedury publikacji aplikacji. Dla środowiska zdalnego potrzebujesz też kontroli dostępu i zasobów; kontekst znajdziesz w artykule czym jest VPS.
Najczęstsze pytania
Czy Compose Watch zastępuje bind mount?
Nie musi. To alternatywny sposób dostarczania zmian do kontenera, z regułami wyboru akcji i ignorowania plików. Bind mount nadal jest przydatny, gdy chcesz bezpośrednio udostępnić katalog hosta.
Dlaczego po sync muszę restartować aplikację?
Proces może wczytywać kod lub konfigurację tylko podczas startu. Synchronizacja aktualizuje plik, ale nie narzuca aplikacji ponownego odczytu. Dobierz reloader, restart albo przebudowę do zachowania programu.
Czy rebuild usuwa moje dane?
Odtworzenie kontenera usuwa jego roboczą warstwę. Dane wymagające trwałości powinny być zaprojektowane osobno, na przykład w odpowiednim wolumenie. Ten przykład zawiera wyłącznie odtwarzalne pliki strony, bez bazy danych.
Czy Watch działa bez otwartego terminala?
Proces obserwujący musi działać. Zamknięcie sesji może go zakończyć, choć sama usługa może pozostać uruchomiona w zależności od sposobu startu. Sprawdź docker compose ps i świadomie zakończ projekt.
Czy mogę używać Watch na produkcji?
Techniczna możliwość nie oznacza dobrego procesu wydawania. Dla produkcji lepszy jest jawny build, test i kontrolowane wdrożenie wersji. Watch wykorzystuj do skrócenia pętli pracy nad kodem.
Źródła
- Use Compose Watch, Docker.
- Compose Develop Specification, Docker.
- docker compose watch, Docker.
- Building best practices, Docker.
- Services reference, Docker.
- Build context and .dockerignore, Docker.
- http.server, Python Software Foundation.
Data publikacji: 01.10.2026.

Dyskusja