Docker Compose: ściąga poleceń na serwer

Polecenia Compose używane w praktyce

Docker Compose udostępnia ponad czterdzieści podpoleceń. W codziennej pracy na serwerze używa się około tuzina. Na tej stronie pogrupowano je według wykonywanego zadania, podano jedno proste uzasadnienie dla każdego z nich oraz wskazano szczegółowe omówienie w przypadkach, gdy polecenie ma istotną pułapkę.

Wszystkie opisane tu polecenia dotyczą Compose V2: docker compose ze spacją, a nie starego skryptu docker-compose. Wersja V2 jest wtyczką napisaną w Go, instalowaną razem z Docker Engine. Wersja V1 nie występuje już w bieżących pakietach, dlatego komunikat docker-compose: command not found na świeżo zainstalowanym systemie Ubuntu w lipcu 2026 jest oczekiwany i nie oznacza awarii. Sprawdź to za pomocą docker compose version. Jeśli polecenie nie zwróci żadnego wyniku, zainstaluj pakiet docker-compose-plugin.

Każde z poniższych poleceń należy uruchamiać z katalogu zawierającego plik compose.yaml, ponieważ Compose pobiera nazwę projektu z tego katalogu i wyszukuje w nim plik. Uruchomienie tego samego polecenia poziom wyżej powoduje zakończenie działania Compose z komunikatem no configuration file provided: not found. Jeśli format pliku jest nowy, zacznij od pierwszego pliku Compose na VPS, a następnie wróć tutaj po omówienie poleceń.

Cykl życia: cztery polecenia uruchamiane z klawiatury i jedno usuwające 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. Kończy działanie natychmiast po utworzeniu kontenerów. Dlatego skrypt wdrożeniowy, który następnie wykonuje sondę curl, często kończy się niepowodzeniem przy pierwszej próbie. up -d --wait blokuje działanie do chwili, gdy każda usługa z deklaracją healthcheck zgłosi stan healthy, i kończy działanie z niezerowym kodem, jeśli któraś z nich nigdy nie osiągnie tego stanu. Flaga działa tylko tak dobrze, jak kontrola, która się za nią znajduje. Dlatego przed użyciem jej w automatyzacji należy skonfigurować healthcheck, któremu Compose może zaufać.

stop zatrzymuje kontenery i zachowuje je, dlatego start uruchamia te same kontenery z tą samą zapisywalną warstwą. down zatrzymuje kontenery, a następnie usuwa kontenery i sieć projektu. Wszystko, co zostało zapisane wewnątrz kontenera, ale poza wolumenem, zostaje usunięte razem z nimi. Jest to najpoważniejsze nieporozumienie dotyczące Compose. Pełne omówienie różnicy między down i stop wyjaśnia, kiedy powoduje ono problemy.

restart nie jest przeładowaniem. Zatrzymuje i uruchamia ten sam kontener z użyciem konfiguracji, którą kontener już ma. Dlatego zmieniona zmienna środowiskowa, nowy tag obrazu ani zmodyfikowane mapowanie portu nie wywierają żadnego wpływu. Aby zastosować zmianę pliku, należy ponownie uruchomić up -d. Compose porównuje każdą usługę z uruchomionym kontenerem i odtwarza tylko te kontenery, których konfiguracja uległa zmianie.

Zastosowanie zmiany: ponowne utworzenie, pobranie lub przebudowanie

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

Samo up -d nie wykonuje żadnych działań, gdy nic się nie zmieniło. Dzięki temu można bezpiecznie uruchamiać je wielokrotnie. --force-recreate pomija to porównanie i zastępuje każdy kontener, nawet gdy konfiguracja jest identyczna. Jest to najszybszy sposób na usunięcie nietypowego stanu wewnątrz kontenera.

Aktualizacja obrazu wymaga dwóch poleceń, ponieważ wykonują one różne działania. pull pobiera bieżący obraz dla każdego znacznika wymienionego w pliku. Następnie up -d wykrywa, że identyfikator obrazu usługi nie odpowiada uruchomionemu kontenerowi, i ponownie go tworzy. Jeśli pominięto pobieranie, up -d nadal uruchamia zeszłomiesięczny latest i nie zgłasza błędu.

build dotyczy usług, w których zadeklarowano sekcję build: zamiast image:. up -d --build buduje obraz i uruchamia usługę w jednym kroku. Jest to standardowy cykl pracy podczas modyfikowania kodu. --no-cache należy stosować tylko wtedy, gdy warstwa z pamięci podręcznej jest wyraźnie nieaktualna, ponieważ polecenie przebudowuje każdą warstwę od podstaw.

Sprawdzanie uruchomionych elementó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 uruchamiania, nie jest tam widoczna, dopóki nie zostanie dodana opcja -a. Kontener niewidoczny w ps, gdy ps -a pokazuje go jako Exited (1), oznacza typowy stan po nieudanym uruchomieniu. Należy odczytać kod zakończenia, a następnie logi.

logs -f śledzi jednocześnie każdą usługę i poprzedza każdy wiersz nazwą usługi. Jest to właściwy widok, gdy usługi komunikują się ze sobą i istotna jest kolejność zdarzeń. Aby zawęzić wynik, należy podać nazwę usługi. --tail=100 ma znaczenie w przypadku kontenera działającego od miesiąca, ponieważ domyślnie wyświetlana jest cała historia, co powoduje przepełnienie terminala. --since 15m odpowiada na najczęściej zadawane pytanie: co wydarzyło się podczas właśnie przeprowadzonego ponownego uruchomienia.

top wyświetla procesy wewnątrz każdego kontenera. Pozwala to rozróżnić stan „kontener działa” od stanu „proces wewnątrz kontenera działa”. ls wychodzi poza bieżący katalog i wyświetla wszystkie projekty Compose na hoście wraz z ich stanem. Dzięki temu można znaleźć stos uruchomiony trzy miesiące temu.

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 wykonuje polecenie wewnątrz uruchomionego kontenera. run uruchamia nowy kontener na podstawie tej samej definicji usługi. Jest to potrzebne, gdy usługa nie działa wystarczająco długo, aby można było użyć exec. Zawsze należy łączyć run z --rm. Bez tego każde wywołanie pozostawia zatrzymany kontener. Zatrzymane kontenery gromadzą się, aż docker compose ps -a stanie się nieczytelny.

Najpierw należy użyć sh, a dopiero potem bash. Obrazy oparte na Alpine nie zawierają bash, a błąd ma postać exec: "bash": executable file not found in $PATH. Dodanie --no-deps do run pomija zależności usługi. Dzięki temu szybkie sprawdzenie konfiguracji nie uruchamia całej bazy danych.

run --rm web env to najszybszy sposób na sprawdzenie środowiska faktycznie otrzymanego przez usługę po scaleniu wszystkich plików .env, bloków environment: i zmiennych powłoki. Jeśli wartość jest nieprawidłowa, przyczyną jest zwykle kolejność scalania. opis sposobu rozstrzygania przez Compose konfliktów między plikami env i sekretami określa, 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 wszystkie usługi w jednej sieci projektu, a nazwa każdej usługi jest w niej nazwą DNS. Uruchomienie getent hosts db wewnątrz web wyświetla adres IP kontenera, gdy rozpoznawanie nazwy działa, i nie wyświetla nic, gdy nie działa. W ciągu 2 sekund pozwala to sprawdzić, czy te kontenery mogą się wzajemnie komunikować. Jeśli nazwa jest rozpoznawana, ale połączenie jest odrzucane, proces wewnątrz db jest powiązany z 127.0.0.1 zamiast z 0.0.0.0. W związku z tym nie akceptuje pakietów z innego kontenera. Pozostałe informacje dotyczące tego modelu przedstawiono w działanie sieci Compose i DNS usług.

port web 80 wyświetla adres hosta i port, na którym opublikowano port kontenera. Eliminuje to konieczność zgadywania, gdy mapowanie pochodzi ze zmiennej. Publikowanie portu tworzy również regułę zapory zarządzaną przez Docker. Reguła ta ma pierwszeństwo przed własnymi regułami, dlatego usługa uznawana za prywatną może być dostępna z Internetu. Ten przypadek opisano w dlaczego opublikowane porty Docker omijają ufw.

Woluminy 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 woluminy zadeklarowane przez projekt, po jednym w każdym wierszu. Ta lista określa dane, które należy uwzględnić w kopii zapasowej. cp kopiuje plik do kontenera lub z kontenera bez otwierania powłoki. Po stronie kontenera należy użyć formatu service:path.

down -v usuwa te nazwane woluminy razem z kontenerami. Jest to właściwe polecenie do usuwania testowego stosu i niewłaściwe polecenie w przypadku danych, które mają zostać zachowane, ponieważ nie wymaga potwierdzenia i nie można cofnąć jego działania. Montowania bind przetrwają tę operację, ponieważ znajdują się w systemie plików hosta. Ta różnica w zakresie skutków jest jednym z powodów, dla których należy świadomie wybierać między montowaniami bind a nazwanymi woluminami.

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 występują już w pliku. Jest to dokładnie sytuacja po zmianie nazwy usługi. Bez tego te kontenery nadal działają i nie są widoczne dla docker compose ps.

docker system df pokazuje, gdzie zostało wykorzystane miejsce na dysku, zanim cokolwiek zostanie usunięte. Rozdziela obrazy, kontenery, wolumeny lokalne i pamięć podręczną procesu budowania oraz podaje dla każdego elementu ilość miejsca możliwego do odzyskania. image prune -a usuwa każdy obraz, do którego nie odwołuje się żaden tag. Na serwerze, na którym pobrano kilka wersji dużego obrazu, zwykle daje to największą oszczędność miejsca. builder prune czyści pamięć podręczną procesu budowania. Pamięć ta rośnie niezauważenie na każdym serwerze, na którym budowane są własne obrazy.

Żadna z tych operacji nie modyfikuje wolumenu nazwanego. Tylko docker volume prune i docker compose down -v wykonują takie działanie.

Sprawdzanie pliku przed wystąpieniem problemów

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

config --quiet przeprowadza walidację i w przypadku powodzenia niczego nie wyświetla, dlatego należy umieścić je w etapie poprzedzającym wdrożenie lub w hooku git. Zwykłe config wyświetla w pełni scalony i poddany interpolacji plik. Umożliwia to potwierdzenie, że zmienna została rozpoznana, a plik nadpisujący został nałożony zgodnie z oczekiwaniami. Niezdefiniowana zmienna jest wyświetlana 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ą podkomendy, dlatego należy umieścić je przed up. Wyświetla każdą czynność, którą wykonałby Compose, i nie wprowadza żadnych zmian. Poświęcenie trzydziestu sekund przed wykonaniem down na istotnym stosie jest uzasadnione.

Praca z 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

Wiele flag -f jest scalanych w podanej kolejności. Późniejsze pliki zastępują wcześniejsze wartości klucz po kluczu. Jest to standardowy sposób utrzymywania jednego pliku bazowego z niewielkim nadpisaniem dla środowiska produkcyjnego. Reguły różnią się jednak dla list i map, dlatego przed diagnozowaniem nieoczekiwanego wyniku należy przeczytać jak Compose scala wiele plików.

--profile uruchamia usługi oznaczone tym profilem razem z usługami bez oznaczenia. Dzięki temu narzędzia debugowania nie są dołączane do zwykłego up. -p ustawia nazwę projektu, więc dwie kopie tego samego stosu mogą działać równolegle z oddzielnymi sieciami i nazwami woluminów. Przywracanie stosu po ponownym uruchomieniu systemu nie wymaga wpisywania polecenia. Odpowiada za to jednostka, która uruchamia stos automatycznie. Opisano ją w sekcji uruchamianie stosów Compose podczas startu systemu.

FAQ

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

Compose V2, wywoływane jako docker compose ze spacją. Jest to plugin dołączony do Docker Engine, a narzędzie V1 napisane w Pythonie nie jest już instalowane przez aktualne pakiety. Jeśli forma ze spacją niczego nie wyświetla, należy zainstalować pakiet docker-compose-plugin odpowiedni dla danej dystrybucji. Stare skrypty należy zaktualizować do formy ze spacją zamiast dodawać alias, ponieważ V2 ma flagi, których V1 nie obsługiwało.

Dlaczego docker compose restart nie uwzględnia zmiany konfiguracji?

restart zatrzymuje i uruchamia istniejący kontener z konfiguracją używaną podczas jego utworzenia. Nie odczytuje ponownie pliku compose.yaml. Każda zmiana zmiennych środowiskowych, portów, woluminów lub znacznika obrazu wymaga użycia docker compose up -d. Polecenie to porównuje każdą usługę z uruchomionym kontenerem i odtwarza kontenery, które się różnią. Należy dodać --force-recreate, aby wymusić odtworzenie, nawet jeśli zawartość pliku się nie zmieniła.

Jak zaktualizować usługę do nowszego obrazu?

Należy uruchomić docker compose pull, a następnie docker compose up -d. Polecenie pull pobiera bieżący obraz dla każdego znacznika określonego w pliku, a up -d odtwarza każdą usługę, której identyfikator obrazu nie odpowiada już kontenerowi. Samodzielne uruchomienie up -d ponownie wykorzystuje obraz znajdujący się już na dysku. W ten sposób stos przypięty do latest może używać kompilacji sprzed kilku miesięcy bez wyświetlania błędu.

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

docker system df, docker image prune -a i docker builder prune usuwają wyłącznie obrazy oraz pamięć podręczną. Działające usługi nadal funkcjonują, a nazwane woluminy pozostają nienaruszone. Niebezpieczna para to docker compose down -v i docker volume prune. Polecenia te usuwają nazwane woluminy bez pytania o potwierdzenie. Najpierw należy uruchomić docker compose config --volumes, aby ustalić, jakie dane są zagrożone.

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

Tak. docker compose run --rm --no-deps web sh uruchamia pojedynczy kontener na podstawie definicji usługi web, pomija jej zależności i usuwa kontener po zakończeniu. Gdy kontener już działa, należy użyć exec, ponieważ exec dołącza do działającego procesu i wyświetla rzeczywisty stan usługi.