Gdy aplikacja potrzebuje dwóch lub trzech kontenerów, problemem szybko staje się pamiętanie wszystkich parametrów uruchomienia. Jeden wymaga portu, drugi pliku konfiguracyjnego, a oba muszą znaleźć się w tej samej sieci. Docker Compose zapisuje te ustalenia w pliku, z którego odtwarzasz cały projekt jednym poleceniem.
Poniżej uruchomisz dwie współpracujące usługi: małą aplikację HTTP oraz Nginx przekazujący do niej żądania. Przykład pozwala zobaczyć różnicę między portem hosta i kontenera, komunikację po nazwie usługi oraz skutki poleceń up, stop i down. Oba pliki konfiguracyjne znajdziesz w treści.
Co to jest Docker Compose?
Docker Compose to narzędzie do definiowania i uruchamiania aplikacji składających się z usług kontenerowych. Konfigurację zapisujesz w YAML, zwykle w pliku compose.yaml, a następnie zarządzasz projektem przez polecenia docker compose.
Usługa opisuje między innymi obraz, ustawienia uruchomienia i połączenia. Compose może utworzyć na tej podstawie kontenery, sieci i wolumeny. Model ten opisuje dokumentacja How Compose works.
Compose korzysta z Dockera, a nie zastępuje silnika kontenerowego. Jeżeli potrzebujesz uporządkować podstawy, zacznij od wyjaśnienia czym są Docker, obraz i kontener. Tutaj skupiam się na konfiguracji kilku współpracujących elementów.
Warto też rozdzielić Compose i Dockerfile. Dockerfile opisuje budowę obrazu. Plik Compose opisuje uruchomienie usług i ich otoczenia. Projekt może korzystać z gotowych obrazów, jak w poniższym przykładzie, albo budować własne.

Co przygotować przed uruchomieniem przykładu?
Potrzebujesz działającego silnika Docker, dostępnego polecenia Compose oraz wolnego portu 8080 na komputerze, na którym uruchomisz kontenery. Sprawdź narzędzia:
docker version
docker compose version
Pierwsze polecenie powinno pokazać również informacje o serwerze Docker. Sam zainstalowany klient nie wystarcza, jeśli silnik jest zatrzymany albo użytkownik nie może się z nim połączyć.
Docker Desktop zawiera Compose, natomiast na Linuxie sposób instalacji zależy od środowiska. Aktualne warianty przedstawia instrukcja instalacji Compose. W poradniku używam składni docker compose ze spacją. Starsze materiały mogą pokazywać osobny program docker-compose.
Przykład został sprawdzony 24.09.2026 na Linuxie z Docker Engine 29.5.1 i Compose 5.1.3. Test obejmował walidację konfiguracji, odpowiedź HTTP przez Nginx, komunikację po nazwie usługi oraz zatrzymanie i ponowny start. To informacje o środowisku testu, nie minimalne wymagania wersji.
Do pierwszej próby najwygodniejszy jest własny komputer. Jeśli uruchamiasz polecenia przez SSH, hostem Dockera jest zdalny serwer. Adres 127.0.0.1 będzie wtedy odnosił się do tego serwera, a nie do laptopa, na którym masz otwartą przeglądarkę.
Dwa kontenery: aplikacja i Nginx
Utwórz nowy katalog i przejdź do niego:
mkdir compose-demo
cd compose-demo
Zapisz w nim dwa zwykłe pliki tekstowe: compose.yaml i nginx.conf. Zwróć uwagę, aby edytor nie dopisał rozszerzenia .txt. W YAML zachowaj wcięcia ze spacji, bez tabulatorów.
Plik compose.yaml
services:
app:
image: traefik/whoami:v1.11.0
web:
image: nginx:stable-alpine
ports:
- "127.0.0.1:8080:80"
volumes:
- ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
depends_on:
- app
Usługa app używa projektu traefik/whoami: niewielkiego serwera pokazującego informacje o obsługiwanym żądaniu. Dzięki temu łatwo sprawdzisz, czy odpowiedź pochodzi z aplikacji. To narzędzie demonstracyjne, którego nie trzeba udostępniać publicznie.
Usługa web uruchamia Nginx i publikuje jego port 80 jako port 8080 hosta, wyłącznie pod adresem pętli zwrotnej 127.0.0.1. Pole volumes udostępnia plik konfiguracyjny, a końcówka ro oznacza montowanie tylko do odczytu.
Tag stable-alpine jest ruchomy: z czasem może wskazać nowszy obraz. W przykładzie upraszcza wybór odmiany Nginx. Jeśli potrzebujesz odtwarzać dokładnie ten sam artefakt, zapisz jego digest i osobno planuj aktualizacje.
W pliku nie ma pola version. Współczesna specyfikacja Compose uznaje je za przestarzałe. Numer wpisany w dawnym version: "3.8" nie jest numerem zainstalowanego programu Compose.
Plik nginx.conf
server {
listen 80;
location / {
proxy_pass http://app:80;
}
}
Nginx nasłuchuje w swoim kontenerze na porcie 80 i przekazuje żądania do app:80. Nazwa app pochodzi z pliku Compose. Nie wpisujesz tu adresu IP kontenera ani portu 8080 hosta.
Plik musi istnieć przed startem projektu. Montowanie jest typu bind mount: plik z hosta zostaje udostępniony pod wskazaną ścieżką kontenera. To inny mechanizm niż nazwany wolumen zarządzany przez Dockera. Różnice oraz opcję tylko do odczytu opisuje dokumentacja Bind mounts.
Uruchom projekt i sprawdź odpowiedź
W katalogu z obydwoma plikami wykonaj:
docker compose config --quiet
docker compose up -d
docker compose ps
Pierwsze polecenie sprawdza konfigurację bez jej wypisywania. Jeśli zgłosi błąd, popraw plik przed dalszą pracą. up -d tworzy i uruchamia usługi w tle, pobierając potrzebne obrazy, jeśli nie ma ich lokalnie. ps pokazuje stan kontenerów i opublikowane porty.
Otwórz na hoście Dockera adres http://127.0.0.1:8080 albo sprawdź go w terminalu:
curl http://127.0.0.1:8080/
W Windows PowerShell możesz użyć curl.exe, aby wywołać program curl zamiast aliasu. Odpowiedź aplikacji zawiera między innymi pole Hostname i informacje o żądaniu. Konkretne identyfikatory i adresy będą zależały od Twojego środowiska.
Przy pierwszym uruchomieniu procesy mogą potrzebować chwili na start. Jeśli nie ma odpowiedzi, sprawdź:
docker compose logs --tail=50 web app
docker compose exec web nginx -t
Pierwsze polecenie pokazuje końcówkę logów obu usług. Drugie sprawdza składnię konfiguracji Nginx wewnątrz działającego kontenera web. Wynik up -d nie zastępuje sprawdzenia rzeczywistej odpowiedzi aplikacji.
Gotowe pliki do podobnej próby znajdziesz w konfiguracji Nginx i Compose. Polecenia obsługi projektu zebrałem w ściądze Dockera.
Jak kontenery znajdują się w sieci?
Compose tworzy domyślną sieć projektu. Usługi korzystające z niej mogą odnajdywać się po nazwach, dlatego konfiguracja Nginx odwołuje się do app. Nie trzeba ręcznie odczytywać adresu IP kontenera, który może zmienić się po jego odtworzeniu. Zasady opisuje Networking in Compose.
W naszym przykładzie występują trzy różne punkty:
| Miejsce | Adres lub port | Znaczenie |
|---|---|---|
| Host Dockera | 127.0.0.1:8080 |
Wejście do Nginx przez opublikowany port |
Kontener web |
port 80 |
Port, na którym Nginx przyjmuje ruch |
Usługa app w sieci projektu |
app:80 |
Adres aplikacji używany przez Nginx |
Usługa app nie ma sekcji ports, bo w tym ćwiczeniu ma być osiągalna przez Nginx, a nie przez osobny port hosta. Brak publikacji portu nie blokuje komunikacji między usługami we wspólnej sieci.
localhost wewnątrz kontenera oznacza ten kontener. Gdyby Nginx próbował przekazywać ruch do localhost:80, wskazywałby własne środowisko zamiast aplikacji app.

Co zmienia adres 127.0.0.1?
Mapowanie 127.0.0.1:8080:80 ogranicza publikację portu do pętli zwrotnej hosta. Sam zapis 8080:80 domyślnie publikuje port na wszystkich interfejsach hosta. Ma to znaczenie szczególnie na serwerze z publicznym adresem IP. Szczegóły i ograniczenia wersji opisuje Port publishing and mapping.
Jeśli wykonujesz ćwiczenie na VPS, najprościej sprawdzić odpowiedź poleceniem curl w sesji SSH. Brak dostępu pod publicznym adresem serwera jest przy tej konfiguracji oczekiwany. Podstawy wyboru takiego środowiska opisuję w artykule VPS a hosting współdzielony.
Jeżeli aplikacja nadal nie dociera do danych, sprawdź diagnostykę połączenia kontenera z bazą. Pozwala oddzielić problem adresowania od gotowości usługi lub błędnych poświadczeń.
depends_on ustala kolejność, ale nie pełną gotowość
Krótki zapis depends_on: - app ustala zależność przy uruchamianiu usług. Nie sprawdza jednak, czy aplikacja zakończyła inicjalizację i potrafi już obsługiwać żądania. W tym przykładzie serwer jest prosty, lecz przy bazie danych inicjalizacja może trwać dłużej.
Gdy usługa zależna wymaga gotowej bazy, można zdefiniować odpowiedni healthcheck i zależność z condition: service_healthy. Compose zaczeka wtedy na pozytywny wynik wskazanego sprawdzenia. Mechanizm wyjaśnia dokumentacja kolejności startu.
Test zdrowia musi odpowiadać realnej gotowości danej usługi. Samo istnienie procesu to często za mało. Aplikacja powinna też umieć ponowić połączenie po późniejszej awarii zależności, ponieważ kontrola kolejności startu nie zapewnia stałej dostępności przez cały czas działania.
Najważniejsze polecenia podczas pracy
Wykonuj je w katalogu projektu. Dzięki temu Compose znajdzie właściwy plik i zasoby, zamiast operować na innym zestawie usług.
| Polecenie | Do czego służy |
|---|---|
docker compose up -d |
Tworzy lub odtwarza wymagające zmiany kontenery i uruchamia projekt w tle |
docker compose ps |
Pokazuje bieżący stan usług |
docker compose logs -f web |
Śledzi logi usługi web |
docker compose stop |
Zatrzymuje kontenery, pozostawiając je w projekcie |
docker compose start |
Uruchamia istniejące, zatrzymane kontenery |
docker compose down |
Zatrzymuje i usuwa kontenery oraz sieci tworzone dla projektu |
Z obserwowania logów wychodzisz przez Ctrl+C. Jeśli projekt uruchomiono wcześniej w tle przez up -d, zakończenie samego logs -f nie zatrzymuje usług.
Po zmianie konfiguracji Compose ponowne up -d służy do zastosowania zmian. Samo restart nie wczytuje zmian definicji kontenera, takich jak nowe zmienne środowiskowe. Z kolei edycja podmontowanego pliku nginx.conf wymaga przeładowania konfiguracji Nginx lub jego restartu; Compose nie interpretuje zawartości tego pliku za aplikację.

Co stanie się z danymi po down?
Zwykłe docker compose down nie usuwa nazwanych wolumenów. Opcja -v rozszerza usuwanie o wolumeny zadeklarowane w projekcie oraz podłączone wolumeny anonimowe. Zasoby oznaczone jako zewnętrzne mają inne zasady i nie są przez down usuwane. Zakres operacji opisuje dokumentacja polecenia.
Nie oznacza to, że każda informacja zapisana w kontenerze jest bezpieczna. Dane pozostawione wyłącznie w jego zapisywalnej warstwie znikną wraz z usunięciem kontenera. Dla bazy lub przesyłanych plików trzeba świadomie skonfigurować trwałe miejsce zapisu i backup.
Nasze ćwiczenie nie tworzy bazy ani nazwanego wolumenu. Po zakończeniu wykonaj docker compose down. Dwa pliki zapisane w katalogu compose-demo pozostaną na hoście, podobnie jak pobrane obrazy.
Najczęstsze problemy z pierwszym projektem
Port 8080 jest zajęty. Zmień mapowanie na przykład na 127.0.0.1:8081:80, wykonaj docker compose up -d i użyj nowego portu w przeglądarce. Nie musisz zmieniać wewnętrznego portu aplikacji.
Nginx zgłasza problem z plikiem konfiguracji. Sprawdź, czy nginx.conf istnieje jako plik w tym samym katalogu co compose.yaml. Literówka w ścieżce lub katalog utworzony zamiast pliku może uniemożliwić poprawne montowanie. Następnie sprawdź logi web.
Pojawia się 502 Bad Gateway. Sprawdź stan i logi app, adres proxy_pass oraz to, czy oba kontenery należą do właściwego projektu. W razie odtworzenia aplikacji może zmienić się jej adres IP; prosty Nginx z tego ćwiczenia może wymagać restartu, aby ponownie rozwiązać nazwę usługi. Nie traktuj demonstracyjnej konfiguracji jako kompletnego mechanizmu obsługi awarii.
Compose nie znajduje konfiguracji. Upewnij się, że terminal znajduje się w katalogu z compose.yaml. Nazwa projektu domyślnie zależy od katalogu; przy używaniu własnej nazwy przez -p stosuj ją konsekwentnie również przy zatrzymywaniu i usuwaniu zasobów.
Dwa częste przypadki mają osobne ścieżki diagnostyczne: zajęty port hosta oraz kontener, który się wyłącza. Zacznij od komunikatu i logów zamiast usuwać cały projekt.
Czy Compose nadaje się na serwer produkcyjny?
Compose może służyć do uruchamiania aplikacji na pojedynczym serwerze. Docker opisuje taki wariant w przewodniku wdrożenia produkcyjnego. Sam plik YAML nie zapewnia jednak kopii zapasowych, monitoringu, HTTPS ani odporności na awarię całego hosta.
Przed wdrożeniem ustal trwałe przechowywanie danych, sposób aktualizacji obrazów i powrotu do poprzedniej wersji. Oddziel poufne ustawienia od publicznego repozytorium, publikuj tylko potrzebne porty i sprawdź zachowanie po restarcie serwera. Te decyzje są częścią utrzymywania aplikacji.
Przykład z poradnika służy do nauki zależności między usługami. Kiedy potrafisz już wskazać plik konfiguracji, drogę żądania i miejsce zapisu danych, łatwiej rozbudować projekt o rzeczywistą aplikację, bazę lub dodatkową usługę.
Przed zmianą sposobu przechowywania plików zobacz co przetrwa odtworzenie kontenera. Przykładem rozbudowy takiego projektu jest n8n z osobnym runnerem.
Najczęstsze pytania
Czym Docker Compose różni się od Dockera?
Docker uruchamia kontenery, a Compose pozwala opisać i obsługiwać powiązane usługi jako projekt. Compose korzysta z silnika Docker i wymaga działającego środowiska kontenerowego.
Jak uruchomić kilka kontenerów jednym poleceniem?
Zdefiniuj usługi w compose.yaml, a w jego katalogu wykonaj docker compose up -d. Potem sprawdź docker compose ps, logi i rzeczywistą odpowiedź aplikacji. Start kontenerów nie gwarantuje pełnej gotowości wszystkich usług.
Czy nadal trzeba wpisywać version w compose.yaml?
Nie. Pole version jest przestarzałe w aktualnej specyfikacji Compose. Program odczytuje współczesny model konfiguracji bez deklarowania numeru dawnego formatu pliku.
Dlaczego kontener nie łączy się z drugim przez localhost?
Ponieważ localhost wskazuje własne środowisko sieciowe kontenera. We wspólnej sieci Compose użyj nazwy usługi i jej wewnętrznego portu, na przykład app:80, zgodnie z konfiguracją aplikacji docelowej.
Czy docker compose down usuwa dane?
Usuwa kontenery i ich zapisywalne warstwy. Domyślnie zachowuje nazwane wolumeny, ale opcja -v może usunąć również wolumeny projektu. Trwałość danych zależy od miejsca ich zapisu; wolumen nie zastępuje kopii zapasowej.
Kiedy używać stop, a kiedy down?
Użyj stop, gdy chcesz zatrzymać istniejące kontenery i później uruchomić je przez start. Użyj down, gdy chcesz usunąć kontenery i sieci projektu, aby później utworzyć je ponownie przez up.
Źródła
- How Compose works, Docker Docs.
- Overview of installing Docker Compose, Docker Docs.
- whoami, Traefik.
- Version and name top-level elements, Docker Docs.
- Bind mounts, Docker Docs.
- Networking in Compose, Docker Docs.
- Port publishing and mapping, Docker Docs.
- Control startup and shutdown order in Compose, Docker Docs.
- docker compose up, Docker Docs.
- docker compose restart, Docker Docs.
- docker compose down, Docker Docs.
- Use Compose in production, Docker Docs.
Data publikacji: 27.09.2026.

Dyskusja