Docker Compose polecenia: praktyczny cheat sheet

Polecenia Compose używane w codziennej pracy

Docker Compose oferuje ponad czterdzieści podpoleceń. W codziennej pracy na serwerze wykorzystuje się około tuzina. Niniejsza strona grupuje je według wykonywanych zadań, podaje jedno proste uzasadnienie dla każdego z nich oraz wskazuje szczegółowe omówienie w miejscach, gdzie polecenie może kryć pułapki.

Wszystkie opisy dotyczą Compose V2: docker compose ze spacją, a nie starego skryptu docker-compose. V2 to wtyczka Go instalowana wraz z Docker Engine, a V1 została usunięta z aktualnych pakietów, więc komunikat docker-compose: command not found na świeżym systemie Ubuntu w lipcu 2026 roku jest zachowaniem oczekiwanym, a nie błędem. Weryfikację przeprowadza się za pomocą docker compose version. Jeśli polecenie nie zwraca wyniku, należy zainstalować pakiet docker-compose-plugin.

Każde z poniższych poleceń uruchamia się z katalogu zawierającego plik compose.yaml, ponieważ Compose pobiera nazwę projektu z tego katalogu i lokalizuje plik względem niego. Uruchomienie tego samego polecenia poziom wyżej spowoduje przerwanie działania Compose z błędem no configuration file provided: not found. Jeśli format pliku jest nowością, należy zacząć od pierwszego pliku Compose na VPS, a następnie wrócić tutaj po zestaw poleceń.

Cykl życia: cztery polecenia, które wpisujesz, oraz to jedno, które usuwa kontenery

docker compose up -d
docker compose up -d --wait
docker compose stop
docker compose start
docker compose restart web
docker compose down

up -d tworzy sieć, tworzy kontenery, uruchamia je i kończy działanie. Polecenie to zwraca sterowanie natychmiast po utworzeniu kontenerów, dlatego skrypt wdrożeniowy, który bezpośrednio po nim wykonuje test curl, często kończy się niepowodzeniem przy pierwszej próbie. up -d --wait blokuje wykonanie do momentu, aż każda usługa z zadeklarowanym testem healthcheck zgłosi stan gotowości; w przypadku niepowodzenia zwraca kod błędu inny niż zero. Flaga ta jest skuteczna tylko w takim stopniu, w jakim poprawny jest sam test, dlatego przed użyciem jej w automatyzacji warto przygotować healthcheck, któremu Compose może zaufać.

stop zatrzymuje kontenery, zachowując je w systemie, dzięki czemu start przywraca te same kontenery wraz z ich warstwą zapisu. down zatrzymuje kontenery, a następnie usuwa je wraz z siecią projektu. Wszystkie dane zapisane wewnątrz kontenera, poza zamontowanymi wolumenami, zostają trwale usunięte. Jest to najkosztowniejsze nieporozumienie w pracy z Compose, a artykuł pełna różnica między down a stop wyjaśnia, w jakich sytuacjach prowadzi to do problemów.

restart nie jest poleceniem przeładowania konfiguracji. Zatrzymuje ono i uruchamia ten sam kontener z już istniejącą konfiguracją, więc zmiana zmiennej środowiskowej, nowy tag obrazu czy edycja mapowania portów nie przynoszą żadnego efektu. Aby zastosować zmiany w plikach, należy ponownie uruchomić up -d. Compose porównuje każdą usługę z uruchomionym kontenerem i odtwarza tylko te, których konfiguracja uległa zmianie.

Wdrażanie zmian: odtwarzanie, pobieranie lub przebudowywanie

docker compose up -d --force-recreate
docker compose pull && docker compose up -d
docker compose build --no-cache web
docker compose up -d --build web

up -d nie wykonuje żadnych działań, jeśli konfiguracja nie uległa zmianie, co czyni to polecenie bezpiecznym do wielokrotnego uruchamiania. --force-recreate pomija to porównanie i zastępuje każdy kontener, nawet jeśli konfiguracja jest identyczna, dlatego jest to najszybszy sposób na wyczyszczenie nietypowego stanu wewnątrz kontenera.

Aktualizacja obrazu wymaga dwóch poleceń, ponieważ wykonują one różne zadania. pull pobiera aktualny obraz dla każdego tagu wymienionego w pliku. Następnie up -d wykrywa, że identyfikator obrazu usługi nie pasuje do uruchomionego kontenera i odtwarza go. Pominięcie pobierania sprawia, że up -d utrzymuje działanie zeszłomiesięcznego latest bez zgłaszania błędu. Odwrotne ryzyko pojawia się w stosach wielousługowych, gdzie pobranie latest dla wszystkich usług jednocześnie może uszkodzić aplikację, która działała dziesięć sekund wcześniej, dlatego samodzielnie hostowany obszar roboczy AFFiNE przypina każdy ze swoich czterech tagów obrazów.

build ma zastosowanie do usług, które deklarują sekcję build: zamiast image:. up -d --build buduje i uruchamia usługę w jednym kroku, co stanowi standardowy cykl pracy podczas modyfikacji kodu. Polecenie --no-cache należy stosować tylko wtedy, gdy warstwa w pamięci podręcznej jest wyraźnie nieaktualna, ponieważ wymusza ono przebudowanie każdej warstwy od podstaw.

Weryfikacja uruchomionych procesów

docker compose ps
docker compose ps -a
docker compose logs -f --tail=100
docker compose logs --since 15m --timestamps db
docker compose top
docker compose ls

ps wyświetla wyłącznie uruchomione kontenery. Usługa, która uległa awarii podczas startu, nie jest tam widoczna, dopóki nie zostanie dodana flaga -a. Zatem sytuacja, w której kontenera brakuje w ps, podczas gdy ps -a wskazuje jego stan jako Exited (1), jest typowym objawem błędu uruchomienia. Należy odczytać kod wyjścia, a następnie sprawdzić logi.

logs -f monitoruje wszystkie usługi jednocześnie i poprzedza każdą linię nazwą usługi. Jest to widok przydatny, gdy usługi komunikują się ze sobą i kolejność zdarzeń ma znaczenie. Wskazanie nazwy usługi pozwala zawęzić zakres. --tail=100 jest istotne w przypadku kontenera działającego od miesiąca, ponieważ ustawienie domyślne wypisuje całą historię i zaśmieca terminal. --since 15m odpowiada na najczęstsze pytanie: co wydarzyło się podczas ostatniego restartu.

top wyświetla listę procesów wewnątrz każdego kontenera, co pozwala odróżnić stan "kontener działa" od "proces wewnątrz kontenera działa". ls wykracza poza bieżący katalog i wyświetla wszystkie projekty Compose na hoście wraz z ich statusem, co umożliwia odnalezienie stosu uruchomionego przed kilkoma miesiącami.

Uzyskiwanie powłoki wewnątrz usługi

docker compose exec web sh
docker compose exec -u root web sh
docker compose run --rm web env
docker compose run --rm --no-deps web sh

exec uruchamia polecenie wewnątrz kontenera, który już działa. run uruchamia nowy kontener na podstawie tej samej definicji usługi, co jest niezbędne, gdy usługa nie działa wystarczająco długo, aby wykonać w niej run. Zawsze należy łączyć run z --rm, ponieważ bez tego każde wywołanie pozostawia zatrzymany kontener, a ich liczba rośnie, dopóki docker compose ps -a nie stanie się nieczytelne.

Przed użyciem bash warto wypróbować sh. Obrazy oparte na Alpine nie zawierają bash, a błąd objawia się komunikatem exec: "bash": executable file not found in $PATH. Dodanie --no-deps do run pomija zależności usługi, co zapobiega uruchamianiu całej bazy danych podczas szybkiego sprawdzania konfiguracji.

run --rm web env to najszybszy sposób na sprawdzenie środowiska, w którym faktycznie działa usługa, po scaleniu każdego pliku .env, bloku environment: oraz zmiennych powłoki. Gdy wartość jest nieprawidłowa, przyczyną jest zazwyczaj kolejność scalania, a sposób, w jaki Compose rozstrzyga pliki env i sekrety wyjaśnia, które źródło ma pierwszeństwo.

Sieci, porty i rozpoznawanie nazw

docker compose port web 80
docker compose exec web getent hosts db
docker compose config --networks

Compose umieszcza każdą usługę w jednej sieci projektu, a każda nazwa usługi stanowi w niej nazwę DNS. Uruchomienie getent hosts db wewnątrz web wyświetla adres IP kontenera, jeśli rozpoznawanie nazw działa, lub nie wyświetla nic, jeśli nie działa; pozwala to w dwie sekundy sprawdzić, czy kontenery widzą się nawzajem. Jeśli nazwa zostaje rozpoznana, ale połączenie jest odrzucane, proces wewnątrz db jest powiązany z 127.0.0.1 zamiast z 0.0.0.0, przez co nigdy nie zaakceptuje pakietu z innego kontenera. Reszta tego modelu znajduje się w jak działają sieci Compose i DNS usług.

port web 80 wyświetla adres hosta i port, na którym opublikowano port kontenera, co pozwala uniknąć zgadywania, gdy mapowanie pochodzi ze zmiennej. Publikacja portu tworzy również regułę zapory sieciowej, którą Docker zarządza samodzielnie; reguła ta znajduje się przed Twoimi własnymi, więc usługa, którą uznawałeś za prywatną, może być otwarta na Internet. Ten przypadek opisano w dlaczego opublikowane porty Docker omijają ufw. Pozostawienie tych portów nieopublikowanych i umieszczenie przed usługami jednego uwierzytelniającego proxy w sieci projektu jest bezpieczniejszym rozwiązaniem, co zapewnia uruchomienie Authentik jako warstwy logowania jednokrotnego.

Wolumeny i dane

docker compose config --volumes
docker compose cp db:/etc/postgresql/pg_hba.conf ./pg_hba.conf
docker compose down -v

config --volumes wyświetla nazwane wolumeny zadeklarowane w projekcie, po jednym w wierszu. Ta lista określa zakres danych wymagających kopii zapasowej. Gdy wolumeny przechowują niezastąpione dane, precyzyjna komenda tworzenia kopii jest równie istotna co sama lista, dlatego porównanie PhotoPrism i Immich szczegółowo opisuje komendy zrzutu i kopiowania wymagane przez każdy z serwerów zdjęć. cp kopiuje plik do lub z kontenera bez otwierania powłoki, wykorzystując format service:path po stronie kontenera.

down -v usuwa nazwane wolumeny wraz z kontenerami. Jest to właściwa komenda do usuwania stosu testowego, lecz niewłaściwa w przypadku przechowywania istotnych danych, ponieważ operacja nie wymaga potwierdzenia i nie można jej cofnąć. Montowania typu bind mounts przetrwają tę operację, gdyż znajdują się w systemie plików hosta. Ta różnica w zasięgu działania jest jednym z powodów, dla których należy świadomie wybierać między montowaniami typu bind mounts a nazwanymi wolumenami.

Czyszczenie zwalniające miejsce na dysku bez utraty danych

docker compose down --remove-orphans
docker system df
docker image prune -a
docker builder prune

--remove-orphans usuwa kontenery należące do projektu, które nie znajdują się już w pliku, co jest typowym efektem zmiany nazwy usługi. Bez tego polecenia kontenery te nadal działają, pozostając niewidocznymi dla docker compose ps.

docker system df pokazuje, co zajmuje miejsce na dysku przed usunięciem jakichkolwiek danych, rozdzielając obrazy, kontenery, wolumeny lokalne oraz pamięć podręczną budowania wraz z informacją o możliwej do odzyskania przestrzeni dla każdego z nich. image prune -a usuwa wszystkie obrazy, do których nie odwołuje się żaden tag; na serwerze, na którym pobierano wiele wersji dużego obrazu, jest to zazwyczaj najbardziej efektywny sposób odzyskania miejsca. builder prune czyści pamięć podręczną budowania, która stopniowo rośnie na każdym serwerze budującym własne obrazy.

Żadne z powyższych poleceń nie usuwa nazwanych wolumenów. Robią to wyłącznie docker volume prune oraz docker compose down -v.

Weryfikacja pliku przed wystąpieniem awarii

docker compose config --quiet
docker compose config --services
docker compose --dry-run up -d

config --quiet sprawdza poprawność i nie wyświetla żadnych komunikatów w przypadku powodzenia, dlatego należy go używać w kroku przed wdrożeniem lub w git hook. Zwykłe polecenie config wyświetla w pełni scalony i zinterpolowany plik, co pozwala potwierdzić, czy zmienna została poprawnie rozwiązana, a plik nadpisań nałożony zgodnie z oczekiwaniami. Niezdefiniowana zmienna pojawi się tam jako pusta wartość, obok ostrzeżenia The "X" variable is not set. Defaulting to a blank string..

--dry-run jest flagą globalną, a nie flagą podpolecenia, dlatego umieszcza się ją przed up. Wyświetla ona wszystkie akcje, które wykonałby Compose, nie wprowadzając przy tym żadnych zmian. Jest to trzydzieści sekund, które warto poświęcić przed wykonaniem down na istotnym stosie usług.

Praca z wieloma plikami, profilami i projektami

docker compose -f compose.yaml -f compose.prod.yaml up -d
docker compose --profile debug up -d
docker compose -p staging up -d

Wielokrotne użycie flag -f powoduje ich łączenie w podanej kolejności, przy czym późniejsze pliki nadpisują wcześniejsze klucz po kluczu. Jest to standardowy sposób utrzymywania jednego pliku bazowego z niewielkim nadpisaniem dla środowiska produkcyjnego, jednak zasady różnią się dla list i map, dlatego przed debugowaniem nieoczekiwanych zachowań należy przeczytać sposób łączenia wielu plików przez Compose.

Flaga --profile uruchamia usługi oznaczone danym profilem wraz z usługami nieoznaczonymi, co pozwala na wykluczenie narzędzi diagnostycznych z typowego polecenia up. Flaga -p ustawia nazwę projektu, dzięki czemu dwie kopie tego samego stosu mogą działać równolegle, korzystając z oddzielnych sieci i nazw wolumenów. Przywrócenie stosu po restarcie nie wymaga wpisywania polecenia; służy do tego jednostka systemowa, która wykonuje to automatycznie, zgodnie z opisem w uruchamianiu stosów Compose podczas startu systemu.

FAQ

Co zastąpiło docker-compose z łącznikiem?

Compose V2, wywoływany jako docker compose ze spacją. Jest to wtyczka dołączona do Docker Engine, a narzędzie w wersji V1 oparte na Pythonie nie jest już instalowane przez bieżące pakiety. Jeśli wywołanie ze spacją nie zwraca żadnych informacji, należy zainstalować pakiet docker-compose-plugin dla danej dystrybucji. Stare skrypty należy zaktualizować do formatu ze spacją zamiast dodawać alias, ponieważ V2 posiada flagi, których V1 nie obsługiwało.

Dlaczego docker compose restart nie uwzględnia zmian w konfiguracji?

restart zatrzymuje i uruchamia istniejący kontener z konfiguracją, z którą został utworzony, i nigdy nie odczytuje ponownie compose.yaml. Każda zmiana zmiennych środowiskowych, portów, wolumenów lub tagu obrazu wymaga użycia docker compose up -d, które porównuje każdą usługę z uruchomionym kontenerem i odtwarza te, które się różnią. Należy dodać --force-recreate, jeśli wymuszenie zastąpienia kontenerów jest wymagane, nawet gdy zawartość pliku nie uległa zmianie.

Jak zaktualizować usługę do nowszego obrazu?

Należy wykonać docker compose pull, a następnie docker compose up -d. Polecenie pull pobiera aktualny obraz dla każdego tagu w pliku, a up -d odtwarza każdą usługę, której ID obrazu nie jest już zgodne z uruchomionym kontenerem. Uruchomienie samego up -d powoduje ponowne użycie obrazu znajdującego się już na dysku, co sprawia, że stos przypięty do latest może korzystać z wersji sprzed miesięcy bez zgłaszania błędów.

Które polecenia czyszczące są bezpieczne na działającym serwerze?

docker system df, docker image prune -a oraz docker builder prune usuwają jedynie obrazy i pamięć podręczną, więc działające usługi pracują bez zakłóceń, a nazwane wolumeny pozostają nienaruszone. Niebezpieczną parą są docker compose down -v oraz docker volume prune, które usuwają nazwane wolumeny bez pytania o potwierdzenie. Należy najpierw uruchomić docker compose config --volumes, aby sprawdzić, co jest zagrożone usunięciem.

Czy można uruchomić jedno polecenie bez startowania całego stosu?

Tak. docker compose run --rm --no-deps web sh uruchamia pojedynczy kontener na podstawie definicji usługi web, pomija zależności i usuwa kontener po wyjściu. Należy użyć exec, gdy kontener już działa, ponieważ exec łączy się z aktywnym procesem i pokazuje stan, w którym usługa faktycznie się znajduje.