docker build

Buduje obraz z Dockerfile w podanym kontekście.

docker build to polecenie, które bierze Dockerfile oraz tak zwany kontekst budowania (zwykle katalog z plikami projektu) i na ich podstawie składa gotowy obraz kontenera. Każda instrukcja w Dockerfile (FROM, COPY, RUN itd.) tworzy warstwę, a wynik dostaje swoje ID i opcjonalnie tag. To pierwszy krok, zanim cokolwiek odpalisz przez docker run czy wypchniesz do rejestru. Od kilku wersji Dockera za samym docker build stoi domyślnie BuildKit (przez Buildx), więc dostajesz cache, równoległość i lepsze logi bez dodatkowej konfiguracji.

Składnia i najważniejsze opcje

Podstawowa forma: docker build [OPCJE] ŚCIEŻKA | URL | -. Najczęściej po prostu docker build -t nazwa:tag ., gdzie kropka to kontekst (bieżący katalog).

  • -t, --tag — nadaje obrazowi nazwę i tag, np. app:1.0; można podać wielokrotnie.
  • -f, --file — wskazuje inny plik niż domyślny Dockerfile, np. Dockerfile.prod.
  • --build-arg — przekazuje zmienną do instrukcji ARG w Dockerfile.
  • --no-cache — ignoruje cache i przebudowuje wszystkie warstwy od zera.
  • --target — buduje tylko do wskazanego etapu w multi-stage Dockerfile.
  • --platform — ustawia docelową platformę, np. linux/amd64 albo linux/arm64.
  • --pull — zawsze pobiera świeższą wersję obrazu bazowego z FROM.
  • -q, --quiet — ucisza logi i wypisuje tylko ID gotowego obrazu.

Przykłady użycia

  • docker build -t mojaapka:latest . — buduje obraz z Dockerfile w bieżącym katalogu i taguje go jako mojaapka:latest.
  • docker build -f docker/Dockerfile.prod -t mojaapka:prod . — używa konkretnego pliku, ale kontekst dalej bierze z kropki.
  • docker build --build-arg NODE_VERSION=20 -t front:dev . — wstrzykuje wersję Node do budowy przez ARG NODE_VERSION.
  • docker build --no-cache --pull -t app:fresh . — pełna przebudowa bez cache i ze świeżym obrazem bazowym, gdy coś dziwnie się zacięło.
  • docker build --target builder -t app:build . — zatrzymuje budowę na etapie builder, przydatne do debugowania multi-stage.

Częste błędy i pułapki

Najpopularniejsza wpadka to zapomniana kropka na końcu — docker build -t app . bez tej kropki to błąd, bo Docker nie wie, gdzie jest kontekst. Pamiętaj też, że cały kontekst jest pakowany i wysyłany do demona, więc budowanie w katalogu domowym z gigabajtami śmieci potrafi trwać wieczność — używaj .dockerignore, żeby wyciąć node_modules, .git i logi. ARG nie jest dostępne w działającym kontenerze ani po FROM, jeśli go ponownie nie zadeklarujesz, a wartości --build-arg potrafią wyciec do historii obrazu — nie wkładaj tam haseł (od tego są sekrety BuildKit). Na koniec uwaga sprzętowa: obraz zbudowany na Macu z procesorem ARM nie odpali na serwerze x86, jeśli nie ustawisz --platform.

Powiązane komendy: docker run, docker images, docker push, docker tag, docker buildx, docker compose build.