Docker Compose build czy image: różnice i konfiguracja
Wyjaśnienie różnic między parametrami build oraz image w Docker Compose na VPS. Dowiedz się, dlaczego zmiany w Dockerfile są ignorowane i jak wymusić aktualizację obrazu.
Docker Compose: build kontra image – krótkie wyjaśnienie
W pliku Docker Compose parametr image: określa obraz, który ma zostać użyty, w tym obraz lokalny, tag lub referencję typu digest, natomiast build: informuje Compose, jak zbudować obraz ze źródeł. Ustawienie tylko image: powoduje, że Compose używa lub pobiera obraz zgodnie z pull_policy. Ustawienie tylko build: sprawia, że Compose buduje obraz przy użyciu skonfigurowanego mechanizmu budowania, nadając mu nazwę pochodzącą od nazwy projektu i nazwy usługi. Ustawienie obu parametrów sprawia, że pull_policy decyduje, czy Compose pobiera, czy buduje obraz; w przypadku budowania, wynik jest oznaczany nazwą z image:, co pozwala na zbudowanie obrazu i wypchnięcie go pod wybraną nazwą. Mechanizm budowania może działać lokalnie lub na zdalnym hoście Docker.
To cała różnica. Poniżej opisano, co oznacza to w praktyce podczas pracy na serwerze. Zakłada się, że Docker Engine oraz wtyczka Compose są już zainstalowane; uruchamianie Docker na VPS opisuje ten etap.
Trzy formy w pełnym zakresie
Użyj opublikowanego tagu, pobierając go, jeśli brakuje go w domyślnej polityce pobierania. Na żadnym etapie nie jest używany Dockerfile.
services:
web:
image: nginx:1.27
restart: unless-stopped
ports:
- "80:80"Budowanie z pliku Dockerfile znajdującego się w katalogu projektu. Proces budowania może również pobierać obrazy i pobierać zależności wymagane przez Dockerfile.
services:
web:
build: .
restart: unless-stopped
ports:
- "80:80"Budowanie i tagowanie wyniku za pomocą docker compose build; bez jawnej polityki pobierania, up próbuje pobrać ten obraz przed rozpoczęciem budowania. docker compose push może następnie wysłać ten konkretny tag do rejestru.
services:
web:
build:
context: .
dockerfile: Dockerfile
image: registry.example.com/acme/web:1.4.2
restart: unless-stopped
ports:
- "80:80"context to katalog wysyłany do mechanizmu budującego. dockerfile jest rozwiązywana względem tego kontekstu, więc context: . z dockerfile: docker/prod.Dockerfile jest standardowym i poprawnym rozwiązaniem. Uruchom docker compose images, aby zobaczyć nazwę obrazu oraz ID obrazu przypisane do każdego kontenera usługi; sprawdź plik Compose, aby potwierdzić, czy usługa używa image:, build:, czy obu tych elementów.
Dlaczego docker compose up nie buduje obrazu ponownie po zmianie Dockerfile?
Ponieważ standardowe up używa ponownie istniejącego obrazu, chyba że wymusisz budowanie lub skonfigurujesz odpowiednią politykę.
Gdy Compose uruchamia usługę posiadającą tylko sekcję build:, korzysta z dostępnego obrazu, jeśli taki istnieje. Nie odczytuje pliku Dockerfile, nie porównuje plików źródłowych ani nie sprawdza znaczników czasu. Przy obecności zarówno image:, jak i build: oraz braku jawnego pull_policy, Compose najpierw próbuje pobrać obraz, a buduje go tylko wtedy, gdy nie jest on dostępny w rejestrze lub pamięci podręcznej platformy. Istniejący obraz jest uznawany za wystarczający.
W efekcie edytujesz app.py, uruchamiasz docker compose up -d, obserwujesz komunikat Compose o działającym kontenerze i serwujesz stary kod. Żaden proces nie zakończył się błędem, więc nie otrzymujesz ostrzeżenia. Wskazówką jest status wyświetlany przez Compose obok nazwy kontenera: kontener zastąpiony przez Compose ma status recreated lub started, natomiast kontener, który Compose pozostawił bez zmian, ma status running.
Dwie metody pozwalają to zweryfikować. docker compose images wyświetla ID obrazu używanego przez każdy kontener, więc zanotuj je przed wdrożeniem i porównaj po nim. docker image ls posiada kolumnę CREATED, jednak buforowane budowanie i powtarzalne znaczniki czasu sprawiają, że sama data nie dowodzi, czy najnowsze źródła zostały uwzględnione w budowaniu.
Które flagi wymuszają przebudowanie
docker compose up -d --buildnajpierw buduje, a następnie odtwarza każdy kontener, którego obraz uległ zmianie. Jest to flaga, której poszukuje większość użytkowników.docker compose build webbuduje jedną usługę i nie uruchamia niczego. Należy użyć jej w połączeniu zdocker compose up --no-deps -d web, aby zastąpić tylko ten kontener i pozostawić resztę stosu w działaniu.docker compose build --no-cache webpomija warstwy z pamięci podręcznej i przebudowuje usługę.docker compose build --pullpodejmuje próbę pobrania nowszej wersji obrazu bazowego zFROM, dzięki czemu zmienny tag, taki jaknode:22, pobierze aktualną zawartość zamiast kopii pobranej w marcu.docker compose up -d --force-recreatewymusza odtworzenie kontenera, nawet jeśli konfiguracja i obraz nie uległy zmianie. Sama flaga nie żąda budowania, aleupnadal może wywołać budowanie, jeśli obraz nie istnieje lub wymaga tego polityka pobierania. Sięganie po tę flagę, gdy zamiarem było użycie--build, jest częstym błędem.
Decyzję można również przenieść do pliku. Zgodnie ze specyfikacją Compose, pull_policy: build oznacza, że Compose buduje obraz i przebudowuje go, jeśli już istnieje. Każde up wiąże się wtedy z kosztem budowania, co jest pożądane na laptopie, ale rzadko na serwerze.
services:
web:
build: .
image: registry.example.com/acme/web:dev
pull_policy: buildWarto znać jeszcze jedną interakcję. docker compose pull próbuje pobrać obrazy również dla usług posiadających sekcję build, a jeśli pobieranie się nie powiedzie, informuje, że obraz musi zostać zbudowany. Należy przekazać --ignore-buildable, aby pominąć te usługi bez wyświetlania komunikatów.
Wpływ pamięci podręcznej budowania na czas wdrożenia
Mechanizm budowania sprawdza każdą instrukcję Dockerfile pod kątem możliwości ponownego wykorzystania wyniku z pamięci podręcznej, jeśli instrukcja oraz jej dane wejściowe nie uległy zmianie. W przypadku COPY dane wejściowe obejmują zawartość plików oraz metadane, z wyłączeniem czasu modyfikacji. Gdy jedna warstwa nie zostanie znaleziona w pamięci podręcznej, wszystkie kolejne kroki, które od niej zależą, są budowane ponownie.
Ta jedna zasada decyduje o tym, czy wdrożenie trwa sekundy, czy minuty. Należy układać instrukcje w Dockerfile od tych, które zmieniają się rzadko, do tych, które zmieniają się przy każdym commicie.
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]npm ci znajduje się powyżej COPY . ., więc edycja pliku źródłowego pozostawia warstwę instalacyjną w pamięci podręcznej, a proces budowania wznawia się od kroku kopiowania. Zamiana tych dwóch linii sprawia, że zmiana jednego znaku powoduje ponowną instalację wszystkich zależności, ponieważ COPY . . unieważnia warstwę, na której zbudowano npm ci. Ten sam schemat dotyczy pip install -r requirements.txt oraz go mod download.
--no-cache jest właściwym narzędziem, gdy istnieje podejrzenie, że nieaktualna warstwa maskuje poprawkę. Jest to jednak złe ustawienie domyślne, ponieważ odrzuca korzyści z ponownego wykorzystania warstw, dla których zoptymalizowano kolejność w Dockerfile.
Jedną z rzeczy, które obraz definiuje, a Compose może nadpisać, jest CMD z Dockerfile – to ona uruchamia się domyślnie, chyba że klucz command: w usłudze ją zastąpi. Interakcja między command a entrypoint ma tutaj kluczowe znaczenie, ponieważ nadpisanie w Compose może sprawić, że świeżo zbudowany obraz będzie zachowywał się dokładnie tak samo, jak poprzedni.
Kontekst budowania i .dockerignore
context: . udostępnia katalog projektu dla mechanizmu budującego. Bez wykluczeń obejmuje to .git oraz każdy katalog z danymi znajdujący się obok kodu źródłowego, mimo że BuildKit pomija nieużywane pliki i przesyła zmiany przyrostowo. Jeśli proces budowania zatrzymuje się na etapie przesyłania kontekstu w niezmienionym projekcie, oznacza to, że kontekst jest zbyt duży.
Plik .dockerignore w katalogu głównym kontekstu wyklucza ścieżki z tego transferu. Składnia jest zbliżona do .gitignore.
.git
node_modules
*.log
data/
.envPrzynosi to dwie korzyści. Transfer staje się mniejszy, co skraca czas przesyłania plików. Ponadto COPY . . nie może już skopiować .env do obrazu, skąd każdy użytkownik pobierający obraz mógłby go odczytać.
Przyczyną powolnego budowania, która narasta z czasem, jest bind mount. Wolumen nazwany znajduje się poza katalogiem projektu, ale bind mount, taki jak ./data:/var/lib/postgresql/data, znajduje się wewnątrz kontekstu budowania, więc budowanie staje się coraz wolniejsze w miarę wzrostu bazy danych. Jedna linia w .dockerignore rozwiązuje ten problem. Bind mounts a wolumeny nazwane omawia szersze aspekty tego wyboru.
Argumenty budowania niosą ze sobą mniejsze ryzyko tego samego typu. Wartości przekazywane przez args: mogą pozostać w historii obrazu lub metadanych pochodzenia, dlatego należy umieszczać tam numery wersji, a nigdy tokeny. Predefiniowane argumenty proxy są domyślnie wykluczone z cache budowania oraz docker history, chyba że zostaną jawnie przywołane w Dockerfile. Pliki Env i sekrety w Compose wyjaśnia, gdzie w rzeczywistości powinny znajdować się dane uwierzytelniające.
Czy budować na VPS, czy budować gdzie indziej i pobierać gotowe obrazy?
Budowanie na serwerze obsługującym ruch jest domyślnym rozwiązaniem, ponieważ stanowi najkrótszą ścieżkę: git pull, a następnie docker compose up -d --build. Jest to dopuszczalne na małym serwerze, od którego nikt jeszcze nie zależy. Przestaje to być rozwiązanie poprawne z dwóch powodów, które można zmierzyć, oraz jednego, który ujawnia się tylko w sytuacjach awaryjnych.
Pamięć. Proces budowania uruchamia kompilatory i bundlery obok działającej aplikacji, a są to komponenty o dużym zapotrzebowaniu na pamięć w większości stosów technologicznych. Bundler JavaScript lub kompilacja Rust mogą wyczerpać pamięć dostępną na VPS o pojemności 1 GB. W przypadku wyczerpania pamięci jądro wybiera ofiarę OOM (Out of Memory) na podstawie wskaźnika badness, uwzględniającego zużycie pamięci, kontekst alokacji oraz oom_score_adj; nie jest to po prostu zabicie największego procesu. Proces budowania może zostać przerwany z błędem Killed i statusem wyjścia 137, albo zamiast niego może zostać zabita baza danych, co spowoduje awarię serwisu w trakcie wdrażania. dmesg -T | grep -i oom przeszukuje dziennik jądra w poszukiwaniu komunikatów OOM; dostęp wymaga uprawnień do odczytu tego dziennika.
Dysk. Procesy budowania pozostawiają warstwy obrazów i pamięć podręczną kompilacji. docker system df pokazuje ich zużycie dysku; okresowe czyszczenie pamięci podręcznej przez BuildKit odzyskuje miejsce zgodnie ze skonfigurowanymi politykami. Odzyskaj miejsce za pomocą docker image prune dla nieużywanych obrazów oraz docker builder prune dla warstw pamięci podręcznej. Pełny dysk zatrzymuje nie tylko proces budowania. Baza danych również przestaje zapisywać dane, a koszt tej awarii jest znacznie wyższy niż koszt wolnego wdrażania.
Powtarzalność. Bez wypychania lub eksportowania, obraz zbudowany na serwerze istnieje tylko na tym serwerze. Jeśli stary obraz nie jest już dostępny, wycofanie zmian (rollback) oznacza pobranie starego commita i ponowne budowanie, a ten proces nie gwarantuje uzyskania identycznego wyniku, ponieważ tag bazowy mógł się zmienić, podobnie jak repozytoria pakietów. Budowanie gdzie indziej i wypychanie tagu zmienia wycofanie zmian w prostą edycję: wskaż image: na poprzedni tag i uruchom docker compose up -d.
Rozwiązanie, które sprawdza się w praktyce, jest proste. Ciągła integracja (CI) wykonuje budowanie i wypycha registry.example.com/acme/web:<git-sha>, a plik Compose na VPS zawiera image: bez żadnego klucza build:. Wdrożenie sprowadza się wtedy do dwóch poleceń, które niemal nie zużywają pamięci.
docker compose pull
docker compose up -dUruchom docker login registry.example.com na serwerze, aby zapisać poświadczenia niezbędne do pobierania prywatnych tagów.
Zachowaj sekcję budowania na potrzeby środowiska programistycznego zamiast ją usuwać, umieszczając ją w pliku o własnej nazwie.
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --buildNazwij ten plik compose.dev.yaml, a nie compose.override.yaml. Compose automatycznie ładuje plik nadpisujący, jeśli jest obecny, więc przypadkowo skopiowany na serwer plik nadpisujący mógłby po cichu uruchomić budowanie bezpośrednio na serwerze. Łączenie kilku plików Compose wyjaśnia, w jaki sposób mechanizm łączenia rozstrzyga poszczególne klucze.
Pułapka architektury przy budowaniu na innym sprzęcie
Pojedynczy obraz platformy zawiera architekturę CPU, dla której został zbudowany. Zbudowanie obrazu ARM na laptopie z Apple Silicon, wypchnięcie go, a następnie użycie na VPS z x86_64 powoduje, że Docker ostrzega podczas tworzenia kontenera, jeśli używany jest niekompatybilny obraz z pamięci podręcznej bez jawnie określonej platformy. Bez emulacji proces kończy się błędem exec format error, który wygląda jak uszkodzony plik binarny, choć nim nie jest. Należy budować obraz jawnie dla docelowej architektury:
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .Ten sam problem występuje w drugą stronę, jeśli laptop posiada architekturę x86, a uruchamiany jest VPS z architekturą ARM zamiast x86. Zlecenie budowania w CI na architekturze docelowej eliminuje ten problem. Obraz wieloplatformowy również rozwiązuje tę kwestię: Docker wybiera pasujący wariant podczas pobierania.
Co sprawdzić po wdrożeniu
docker compose imageswyświetla obraz i tag dla każdego uruchomionego kontenera. Zmieniony identyfikator obrazu stanowi dowód, że nowa kompilacja jest w użyciu.docker compose configwyświetla scalony plik po podstawieniu zmiennych, co pozwala odczytać ostateczną nazwę obrazu, której użyje Compose, przed uruchomieniem czegokolwiek.docker compose logs -f webprzez pierwsze pół minuty po zamianie. Kontener, który uruchamia się i kończy działanie, restartuje się tylko wtedy, gdy wymaga tego polityka restartu; przyczynę należy sprawdzić w logach.docker image lspokazuje kolumnę CREATED. Należy sprawdzić wynik kompilacji oraz identyfikator wdrożonego obrazu, ponieważ sam znacznik czasu utworzenia nie potwierdza, czy przebudowa została wykonana.
Jeśli plik, dla którego wykonywane są te sprawdzenia, jest w trakcie tworzenia, podstawy pliku Compose na VPS omawiają kluczowe elementy, a ściąga poleceń Compose zawiera listę pozostałych podpoleceń.
FAQ
Czy mogę używać build i image w tej samej usłudze?
Tak, jest to standardowa konfiguracja dla projektów budowanych samodzielnie. Gdy Compose buduje obraz na podstawie sekcji build:, oznacza wynik wartością z image:. Bez jawnego pull_policy, up najpierw podejmuje próbę pobrania obrazu. Ten tag jest używany przez docker compose push do wysyłki do rejestru oraz przez inne maszyny do pobrania. Bez klucza image: Compose nadal przeprowadzi budowanie, ale nada obrazowi nazwę pochodzącą od projektu i usługi oraz wyświetli ostrzeżenie, że brak atrybutu uniemożliwia wysłanie obrazu.
Dlaczego docker compose up nie uwzględnia zmian w Dockerfile?
Ponieważ standardowe up używa istniejącego obrazu, chyba że wymusisz budowanie lub skonfigurujesz politykę, która go wymaga. Narzędzie nie porównuje obrazu z plikiem Dockerfile ani plikami źródłowymi w celu podjęcia decyzji o ponownym budowaniu. Uruchom docker compose up -d --build lub wykonaj docker compose build web, a następnie docker compose up --no-deps -d web, aby zastąpić pojedynczą usługę. Ustawienie pull_policy: build w usłudze sprawia, że każde up wymusza ponowne budowanie, co jest przydatne na maszynie programistycznej.
Jaka jest różnica między --build a --force-recreate?
--build buduje obraz ponownie, a następnie odtwarza kontenery, których obraz uległ zmianie. --force-recreate wymusza odtworzenie kontenera nawet wtedy, gdy konfiguracja i obraz nie uległy zmianie; samo w sobie nie inicjuje budowania. Jeśli zmiana dotyczy kodu źródłowego lub pliku Dockerfile, należy użyć flagi --build. --force-recreate służy do resetowania samego kontenera, na przykład w celu wyczyszczenia warstwy zapisu przy zachowaniu tego samego obrazu.
Czy obrazy Docker należy budować na VPS czy gdzie indziej?
Zaleca się budowanie w innym miejscu i pobieranie gotowego tagu, gdy serwer obsługuje ruch. Proces budowania konkuruje z aplikacją o pamięć RAM, a w przypadku jej wyczerpania jądro systemu wybiera proces do zakończenia (OOM killer), co może dotyczyć bazy danych lub procesu budowania. Budowanie pozostawia również pamięć podręczną na dysku, choć BuildKit odzyskuje ją automatycznie zgodnie z polityką usuwania nieużywanych danych. Budowanie na serwerze jest dopuszczalne w małych projektach bez użytkowników, a późniejsza migracja jest prosta, jeśli sekcja build: zostanie umieszczona w osobnym pliku Compose przeznaczonym tylko do środowiska programistycznego.
Jak zapobiec zapełnianiu dysku przez pamięć podręczną budowania Docker?
Uruchom docker system df, aby sprawdzić, ile miejsca zajmują obrazy oraz pamięć podręczna budowania. docker builder prune usuwa warstwy z pamięci podręcznej, a docker image prune usuwa nieużywane obrazy (dangling images) pozostałe po wcześniejszych budowaniach. Dodanie -a usuwa całą nieużywaną pamięć podręczną budowania lub wszystkie obrazy niepowiązane z kontenerami; nie gwarantuje to jednak całkowicie "czystego" kolejnego budowania. Nie należy planować automatycznego uruchamiania docker system prune -af --volumes na serwerze, ponieważ usuwa ono zatrzymane kontenery oraz nieużywane wolumeny anonimowe, co stwarza ryzyko utraty danych bazy danych przechowywanych w wolumenach anonimowych podczas prac konserwacyjnych.