Czego szukasz?

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

← Wszystkie artykuły

Docker Compose: co to jest i jak uruchomić kilka kontenerów razem?

Papierowy plan konfiguracji połączony z dwoma pomieszczeniami symbolizującymi usługi wspólnego projektu

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.

Plik compose.yaml wskazujący usługi, sieci i wolumeny ujęte we wspólną granicę projektu
Plik compose.yaml opisuje usługi, sieci i wolumeny jednego projektu.

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.

Przeglądarka łączy się przez port 8080 hosta z web, a web przekazuje żądanie do app na porcie 80 w sieci projektu
Port opublikowany na hoście i adres usługi w sieci Compose służą różnym połączeniom.

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

Trzy polecenia Compose zestawione z tworzeniem i uruchomieniem, zatrzymaniem oraz usunięciem kontenerów projektu
Polecenia up, stop i down różnią się tym, co robią z zasobami projektu.

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

Data publikacji: 27.09.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 *