Debugowanie i zarządzanie kontenerami w Docker Compose

1. Wprowadzenie

Wraz ze wzrostem złożoności aplikacji wieloserwisowych (np. frontend + backend + baza danych), coraz większe znaczenie ma umiejętność diagnozowania problemów i efektywne zarządzanie kontenerami. Nawet dobrze skonfigurowany plik docker-compose.yml może wymagać poprawek, np. gdy:

backend nie może połączyć się z bazą danych,
aplikacja frontendowa nie widzi backendu,
jeden z kontenerów się restartuje lub nie uruchamia poprawnie.

Docker Compose udostępnia zestaw komend, które pomagają w debugowaniu, monitorowaniu i utrzymaniu środowiska kontenerowego. W tej lekcji poznasz praktyczne sposoby diagnozowania problemów oraz zarządzania usługami w Compose.

2. Sprawdzanie logów poszczególnych usług

Logi to pierwsze źródło informacji o błędach w kontenerach. W Docker Compose logi wszystkich usług można przeglądać w jednym miejscu lub osobno dla każdej z nich.

2.1 Wyświetlanie logów wszystkich usług

Aby zobaczyć bieżące logi wszystkich uruchomionych kontenerów:

Jeśli chcesz śledzić logi w czasie rzeczywistym (tak jak tail -f w Linuksie):

2.2 Logi konkretnej usługi

Aby wyświetlić logi tylko jednej usługi, np. backendu:

Z opcją -f (follow):

Przykład:

Taki komunikat wskazuje, że backend nie może połączyć się z bazą danych — typowy błąd zależności między kontenerami.

2.3 Ograniczenie liczby linii logów

Aby uniknąć zalewu informacji, można ograniczyć liczbę wyświetlanych wierszy:

Wyświetli tylko 50 ostatnich wpisów logów dla usługi backend.

3. Restartowanie i przebudowa serwisów

Podczas developmentu często trzeba zrestartować kontenery, przebudować obrazy lub ponownie zastosować konfigurację. Docker Compose udostępnia proste polecenia do zarządzania cyklem życia usług.

3.1 Restartowanie usług

Aby zrestartować wszystkie uruchomione kontenery:

Aby zrestartować tylko wybraną usługę:

Restart nie usuwa danych ani nie buduje ponownie obrazów — po prostu zatrzymuje i uruchamia kontenery od nowa, z tą samą konfiguracją.

3.2 Przebudowa obrazów

Jeśli zmieniono plik Dockerfile lub kod źródłowy aplikacji, konieczne jest zbudowanie nowego obrazu:

Aby przebudować tylko wybraną usługę:

Aby wymusić pełne przebudowanie z pominięciem cache:

3.3 Restart z przebudową

Jeśli chcesz jednocześnie przebudować obrazy i uruchomić kontenery:

To najczęściej używane polecenie podczas developmentu — Compose przebuduje obrazy, zaktualizuje kontenery i uruchomi wszystko w tle.

4. Diagnostyka problemów z siecią i zależnościami

W aplikacjach wieloserwisowych problemy sieciowe i zależności między kontenerami są częste. Najczęstsze objawy:

backend nie widzi bazy danych (Connection refused),
frontend nie potrafi połączyć się z API,
usługa uruchamia się, zanim zależna usługa jest gotowa.

4.1 Sprawdzenie stanu usług

Aby zobaczyć, które kontenery są uruchomione, ich status i porty:

Przykład wyniku:

Stan Up oznacza, że kontener działa poprawnie. Jeśli widzisz Exited (1) lub Restarting, oznacza to błąd startu kontenera.

4.2 Inspekcja sieci Compose

Compose tworzy automatycznie sieć typu bridge, w której wszystkie kontenery komunikują się po nazwach usług. Aby zobaczyć szczegóły sieci:

Wynik może wyglądać tak:

Szczegóły konkretnej sieci:

Zobaczysz m.in. adresy IP i połączenia między kontenerami.

4.3 Sprawdzenie połączeń między kontenerami

Możesz wejść do kontenera i ręcznie sprawdzić połączenie:

Następnie przetestować połączenie z bazą:

lub (jeśli masz zainstalowanego klienta psql)

Jeśli ping działa, sieć jest skonfigurowana poprawnie — problem może być w konfiguracji aplikacji lub kolejności uruchamiania.

4.4 Zależności między usługami (`depends_on`)

W Compose można wymusić kolejność startu kontenerów za pomocą depends_on:

To zapewnia, że kontener db zostanie uruchomiony wcześniej, ale nie gwarantuje, że baza będzie już gotowa do połączenia. Aby rozwiązać ten problem, można:

dodać skrypt oczekiwania (wait-for-it.sh lub dockerize),
lub skonfigurować retry logic w aplikacji backendowej.

4.5 Usuwanie niepoprawnych kontenerów i danych

Czasem najlepszym rozwiązaniem jest "czyste" uruchomienie środowiska:

Aby usunąć również wolumeny (czyli dane bazy itp.):

Następnie ponownie uruchomić:

5. Dodatkowe narzędzia diagnostyczne

5.1 Podgląd zasobów systemowych

Aby zobaczyć, ile CPU i RAM zużywają poszczególne kontenery:

Przykładowy wynik:

Dzięki temu możesz wykryć np. usługi z nadmiernym zużyciem pamięci.

5.2 Podgląd logów systemowych Dockera

Jeśli kontener nie startuje i nie daje logów przez Compose, możesz sprawdzić logi silnika Dockera:

(lub w systemach Windows/macOS – przez Docker Desktop → Logs)

5.3 Wejście do kontenera

W celu ręcznego debugowania możesz otworzyć terminal w działającym kontenerze:

lub (jeśli ma zainstalowanego bash):

Pozwala to np. przeglądać pliki, sprawdzać konfigurację, testować połączenia czy edytować ustawienia.

6. Typowe scenariusze problemów i ich rozwiązania

Problem	Objawy	Rozwiązanie
Backend nie łączy się z bazą danych	`Connection refused` lub `timeout`	Sprawdź `depends_on`, sieć, nazwę hosta (powinna być `db`, nie `localhost`).
Frontend nie widzi backendu	Błąd `CORS` lub `Network Error`	Upewnij się, że w pliku `.env` frontendu `API_URL` wskazuje na `http://backend:5000`.
Kontener się restartuje w pętli	`Restarting (1)` w `docker-compose ps`	Sprawdź logi (`docker-compose logs -f`), może brakować zależności lub zmiennej środowiskowej.
Baza nie zapisuje danych po restarcie	Dane znikają po `down`	Dodaj wolumen (`docker volume create` lub sekcja `volumes:` w Compose).
Zmiany w kodzie nie są widoczne	Backend uruchamia starą wersję	Użyj `docker-compose up --build`, upewnij się, że katalog jest zamontowany (`volumes:`).

7. Dobre praktyki debugowania

Zawsze zaczynaj od logów (docker-compose logs -f).
Używaj docker-compose ps, aby sprawdzić stan i porty usług.
Korzystaj z docker exec -it, by wejść do środka kontenera i sprawdzić działanie.
Utrzymuj porządek w wolumenach i sieciach (docker system prune, docker volume ls).
Oddziel konfiguracje środowisk (.env.dev, .env.prod).
Dodaj retry lub opóźnienie startu dla usług zależnych (np. backend czekający na bazę).
Stosuj tagi wersji obrazów (postgres:15.3, nie latest), aby uniknąć niekompatybilności.

8. Podsumowanie

W tej lekcji nauczyłeś się, jak skutecznie debugować i zarządzać kontenerami w środowisku Docker Compose. Poznałeś polecenia i techniki, które pomogą Ci utrzymać stabilność i szybko rozwiązywać problemy:

Analiza logów – docker-compose logs, -f, --tail.
Restart i przebudowa – docker-compose restart, build, up --build.
Diagnostyka sieci i zależności – docker network inspect, docker exec, depends_on.
Zarządzanie danymi i wolumenami – docker-compose down -v.
Monitorowanie wydajności – docker stats.

Dzięki tym narzędziom możesz szybko diagnozować błędy, modyfikować konfigurację i utrzymywać środowisko w pełni funkcjonalne — zarówno w fazie developmentu, jak i produkcji.