Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

Docker Compose Watch: automatyczny rebuild aplikacji podczas programowania

Ceramiczny ołówek, okrągłe strzałki i okno przeglądarki na jasnym tle

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
Porównanie sync, sync+restart i rebuild na trzech poziomych wierszach
Compose Watch może kopiować pliki, restartować usługę albo przebudowywać obraz.

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.

Plik index.html kopiowany z katalogu site do app/site w kontenerze
Mapowanie określa, gdzie zmieniony plik ma trafić wewnątrz kontenera.

.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.

Okrągła pętla od zapisu pliku przez reakcję Compose do sprawdzenia strony
Zapis pliku, reakcja Compose i sprawdzenie wyniku tworzą krótką pętlę pracy.

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

Data publikacji: 01.10.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *