Docker od zera: jak zbudować pierwszy obraz i uruchomić własny kontener

Co to jest Docker i kiedy ma sens jego użycie

Podstawowe definicje: obraz, kontener, silnik Docker

Docker rozwiązuje bardzo konkretny problem: jak zapakować aplikację wraz z jej zależnościami w jeden, powtarzalny pakiet, który działa tak samo na różnych maszynach. Ten pakiet to obraz (image), a jego uruchomiona instancja to kontener (container). Wszystkim tym zarządza silnik Docker (Docker Engine) – usługa działająca w tle w systemie operacyjnym.

Obraz Docker to nie jest „żyjący system”, tylko szablon. Zawiera system plików (biblioteki, pliki aplikacji, konfigurację) oraz metadane, jak polecenie startowe. Obraz jest niezmienny: nie modyfikuje się go w locie – zmiany wprowadza się, budując nową wersję obrazu.

Kontener to proces uruchomiony na podstawie obrazu, odizolowany od reszty systemu przestrzeniami nazw (namespaces) i ograniczeniami zasobów (cgroups). W praktyce to zwykły proces systemowy z własnym systemem plików, siecią i często niezależną konfiguracją. Kontener można startować, zatrzymywać, usuwać, bez zmiany obrazu.

Docker Engine to demon (usługa) działający w tle oraz narzędzie docker (CLI), które z nim rozmawia. Demon obsługuje: pobieranie obrazów, budowanie nowych, uruchamianie kontenerów, zarządzanie sieciami i wolumenami.

Jeżeli definicje „obraz” i „kontener” są rozmyte, dalsze kroki będą chaotycznym zgadywaniem. Minimum to zrozumienie: obraz = wzorzec, kontener = działający proces na bazie tego wzorca.

Kontener vs maszyna wirtualna na prostym przykładzie

Maszyna wirtualna (VM) emuluje cały system: sprzęt, kernel, system operacyjny, aplikacje. Kontener działa na tym samym kernelu, co host, ale ma własną przestrzeń użytkową. To przekłada się na różnice praktyczne.

Załóżmy prosty projekt: jedna aplikacja webowa w Pythonie, baza danych PostgreSQL, środowisko developerskie dla 3 programistów. Maszyna wirtualna dla każdego developera to osobny system operacyjny, który trzeba:

• zainstalować i aktualizować (system operacyjny, paczki, zabezpieczenia),
• konfigurować (sieć, porty, wersje Pythona, Postgresa),
• utrzymywać (snapshoty, kopie zapasowe, miejsce na dysku).

Konteneryzacja w tym samym scenariuszu oznacza jedną maszynę hosta (Linux, Windows + WSL2, macOS) i kilka kontenerów: osobny dla aplikacji, osobny dla Postgresa. Współdzielą kernel, ale każdy ma własne biblioteki i konfigurację. „Instalacja” sprowadza się do pobrania obrazu i uruchomienia kontenera z odpowiednimi parametrami.

Konsekwencje praktyczne:

• Czas startu: kontener startuje zwykle w sekundach, VM w dziesiątkach sekund lub minutach.
• Zasoby: jedna VM potrafi zjeść gigabajty RAM-u, kilka kontenerów – znacznie mniej (brak duplikacji całego systemu operacyjnego).
• Elastyczność: zmiana wersji Postgresa to nowy obraz i restart kontenera, nie reinstalacja całego systemu.

Jeśli potrzebna jest pełna izolacja systemowa (inne jądro, inny system operacyjny, ciężkie obciążenia), wirtualizacja ma przewagę. Jeśli chodzi o powtarzalne środowisko aplikacyjne na wspólnym kernelu, kontenery dają mniej narzutu i szybszy cykl pracy.

Typowe zastosowania Dockera: development, testy, CI, małe usługi

Docker sprawdza się szczególnie tam, gdzie dominują powtarzalność i współdzielenie konfiguracji:

• Środowiska developerskie – każdy programista odpala ten sam zestaw kontenerów (baza, cache, API, front). Eliminacja klasycznego „u mnie działa, u ciebie nie”.
• Testy automatyczne – uruchamianie serwisów zależnych na żądanie (np. Postgres, Redis, Elastic) w pipeline CI (GitLab CI, GitHub Actions). Testy nie zależą od konfiguracji konkretnej maszyny buildowej.
• Małe usługi i narzędzia – własny serwer nginx, mały serwis API, cron w kontenerze, jednozadaniowe narzędzia CLI w postaci obrazu, który można odpalać z różnymi parametrami.
• Reprodukowalne debugowanie – odtwarzanie środowiska, w którym wystąpił błąd, na podstawie wersji obrazu i konfiguracji, bez odręcznego ustawiania systemu.

Jeśli kilka osób ma korzystać z tego samego projektu, Docker staje się praktycznie standardem jakości. W mniejszych, jednoosobowych projektach jego rola jest mniej oczywista i wymaga chłodnej oceny kosztów.

Kiedy Docker jest narzędziem na wyrost

Są scenariusze, w których Docker generuje więcej złożoności niż użytecznej wartości:

• Bardzo mały, jednorazowy projekt – pojedynczy skrypt Pythona, który ma być uruchomiony raz na lokalnej maszynie, bez planów dzielenia się środowiskiem ani wdrażania na serwer.
• Brak problemów z zależnościami – jeśli cały stack jest prosty, a wersje bibliotek i narzędzi są stabilne i zbieżne na wszystkich maszynach, kontenery dodają tylko warstwę abstrakcji.
• Środowisko o restrykcyjnych politykach bezpieczeństwa – czasem administracja blokuje Docker Engine, a próba jego wdrożenia kończy się konfliktem z infrastrukturą i dodatkowymi wyjątkami w politykach.
• Zespół bez doświadczenia w konteneryzacji – przy braku minimalnej wiedzy Docker bywa używany jak „magiczny skrót”, a efektem jest zbiór nieutrzymywalnych obrazów, których nikt nie rozumie.

Jeśli głównym problemem są konfliktujące biblioteki i klasyczne „u mnie działa, u ciebie nie”, Docker jest sensownym kandydatem. Jeśli projekt jest mały, lokalny i jednorazowy, konteneryzacja może być tylko obciążeniem procesowym, bez wyraźnego zysku.

Minimum pojęć i narzędzi, które trzeba opanować na start

Podstawowe komendy diagnostyczne: docker version, docker info, docker help

Trzy komendy, które powinny stać się odruchem, zanim zacznie się walczyć z kontenerami:

• docker version – pokazuje wersję klienta (CLI) i serwera (Engine). Jeśli w sekcji „Server” pojawia się błąd, demon Dockera nie działa lub jest niedostępny. Punkt kontrolny: wersja serwera powinna być zgodna z dokumentacją używanych funkcji.
• docker info – szczegółowe informacje: liczba obrazów, liczba kontenerów (running, paused, stopped), sterownik storage, sterownik sieci, zasoby. To podstawowe źródło prawdy przy diagnostyce środowiska.
• docker <komenda> --help – szybka dokumentacja składni i opcji. Regularne używanie tego polecenia jest szybsze i bezpieczniejsze niż szukanie przypadkowych snippetów w sieci.

Jeżeli docker version i docker info nie działają, nie ma sensu dalej debugować problemów z Dockerfile czy docker run. Stabilny daemon Docker to minimum wejścia w dalsze etapy.

Kluczowe pojęcia: obraz, kontener, rejestr, tag, warstwa obrazu

Bez zrozumienia kilku pojęć każdy kolejny krok będzie tylko kopiowaniem przykładów z dokumentacji.

• Obraz (image) – szablon niezmiennego systemu plików i metadane. Obraz może mieć wiele tagów.
• Kontener (container) – instancja obrazu uruchomiona jako proces. Zmiany w kontenerze nie zmieniają obrazu.
• Rejestr (registry) – miejsce przechowywania obrazów, np. Docker Hub, GitHub Container Registry, prywatny registry.
• Tag – etykieta wersji obrazu, np. python:3.11-slim, myapp:1.0.0. To nie osobny obraz, tylko referencja do konkretnego zestawu warstw.
• Warstwa obrazu (layer) – obraz jest złożony z kolejnych warstw tworzonych przez instrukcje w Dockerfile (FROM, RUN, COPY itd.). Warstwy są cache’owane i współdzielone między obrazami.

Praktyczny efekt warstw: jeśli baza obrazu jest wspólna dla kilku projektów (np. python:3.11-slim), host przechowuje ją tylko raz, a kolejne obrazy dokładają własne warstwy. Budowanie jest szybsze, a zużycie dysku – mniejsze.

Struktura ekosystemu: daemon, CLI, Docker Desktop vs Docker Engine

Ekosystem Dockera składa się z kilku elementów, które często są mylone:

• Docker Engine (daemon) – usługa systemowa, która zarządza obrazami, kontenerami, sieciami. W Linuksie to zwykle proces dockerd.
• Docker CLI (klient) – narzędzie docker wywoływane z terminala. Samo w sobie nic nie uruchamia, tylko wysyła polecenia do demona.
• Docker Desktop – paczka dla Windows/macOS, która zawiera Docker Engine (w VM lub poprzez WSL2), CLI oraz GUI do podstawowych operacji. Na Linuksie zwykle instaluje się sam Engine + CLI z repozytoriów.

Na Windows i macOS Docker nie działa natywnie – używana jest wirtualizacja. To wprowadza dodatkowy poziom złożoności (konfiguracja WSL2, dostęp do systemu plików, przydział zasobów). Na Linuksie Docker Engine działa bezpośrednio na hoście, co upraszcza konfigurację i zwiększa wydajność.

Jeśli niejasne jest, czy problem dotyczy CLI, czy demona (Engine), każdy błąd wygląda jak „Docker nie działa”. Pierwszy punkt kontrolny to zawsze sprawdzenie, czy daemon jest uruchomiony i dostępny (docker version, docker info).

Różnice między docker run, docker exec, docker logs w codziennej pracy

W codziennym użyciu Dockera trzy komendy pojawiają się najczęściej:

• docker run – tworzy nowy kontener z obrazu i uruchamia go. Za każdym razem powstaje nowy kontener, chyba że użyjesz --name i spróbujesz go ponownie stworzyć (wtedy pojawi się błąd o istniejącym kontenerze).
• docker exec – uruchamia dodatkowy proces w istniejącym kontenerze, np. powłokę /bin/sh do debugowania. Nie tworzy nowego kontenera.
• docker logs – pokazuje logi z procesu głównego w kontenerze (tego, który został uruchomiony jako CMD/ENTRYPOINT).

Typowy workflow developerski:

1. Utworzenie kontenera: docker run --name myapp -d myimage:tag.
2. Sprawdzenie logów: docker logs myapp.
3. Wejście do środka na potrzeby diagnostyki: docker exec -it myapp sh.

Jeśli ktoś używa docker run do każdego testu, tworząc za każdym razem nowy kontener zamiast pracować na istniejącym lub odtwarzać go kontrolowanie, konteneryzacja szybko zamienia się w bałagan zasobów.

Przygotowanie środowiska: instalacja i pierwszy „health check” Dockera

Dobór sposobu instalacji: Desktop, pakiety, skrypty

Sposób instalacji Dockera powinien wynikać z kilku kryteriów:

• System operacyjny – na Windows i macOS standardem jest Docker Desktop. Na Linuksie – natywne pakiety Docker Engine.
• Poziom uprawnień – brak uprawnień administratora ogranicza możliwości (Docker wymaga uprawnień root lub członkostwa w grupie docker). W niektórych środowiskach firmowych potrzebna jest zgoda administracji.
• Sposób utrzymania – w środowiskach produkcyjnych preferowane są pakiety z oficjalnego repozytorium Dockera lub dystrybucji Linuksa, z kontrolą nad aktualizacjami.

Na stacjach developerskich, przy braku specjalnych wymagań, Docker Desktop jest najszybszym sposobem startu. W środowiskach serwerowych lepiej używać czystego Docker Engine bez GUI oraz z konfiguracją zgodną z politykami organizacji.

Jeśli już na etapie instalacji pojawia się niejasność, czy używany jest Docker Desktop, czy Engine w WSL2, to sygnał, że późniejsze problemy z dyskami i siecią będą trudniejsze do zdiagnozowania. Minimum to jasny obraz architektury: co jest hostem, a co wirtualizacją.

Kroki instalacji na Windows/Mac/Linux – checklisty i pułapki

Windows (Docker Desktop + WSL2)

• Włącz w systemie funkcję WSL2 oraz wirtualizację sprzętową (BIOS/UEFI).
• Zainstaluj z Microsoft Store dystrybucję WSL (np. Ubuntu).
• Pobierz i zainstaluj Docker Desktop dla Windows.
• Skonfiguruj Docker Desktop, wybierając backend WSL2, nie Hyper-V (chyba że są ku temu powody).
• Sprawdź, czy w terminalu PowerShell/WSL działa docker version.

Typowe sygnały ostrzegawcze: błędy o braku WSL2, problemy z uprawnieniami do katalogów Windows z poziomu WSL, nadmierne zużycie RAM przez procesy WSL2.

macOS (Docker Desktop na Intel/Apple Silicon)

• Pobierz instalator Docker Desktop dla właściwej architektury (Intel / Apple Silicon) z oficjalnej strony.
• Zainstaluj aplikację jak typową paczkę .dmg, przenosząc ją do katalogu /Applications.
• Przy pierwszym uruchomieniu zaakceptuj wymagane uprawnienia (sieć, system plików, dostęp do Hypervisor.framework).
• Sprawdź, czy demon startuje poprawnie – ikona Dockera w pasku stanu powinna mieć status „Running”.
• Otwórz terminal i uruchom docker version oraz docker info.

Sygnały ostrzegawcze: Docker Desktop zatrzymujący się samoczynnie (problem z pamięcią, konfliktem z AV), błędy związane z nieobsługiwaną architekturą (np. uruchamianie obrazów amd64 bez emulacji na Apple Silicon), niestabilne działanie przy agresywnych ustawieniach „resources”. Jeśli ikona Dockera stale raportuje restart serwisu, nie ma sensu kontynuować konfiguracji, dopóki to nie zostanie wyjaśnione.

Linux (natywny Docker Engine)

• Usuń potencjalnie konfliktujące pakiety typu docker, docker.io dostarczane przez dystrybucję, jeśli planujesz instalację z repozytorium Dockera.
• Dodaj oficjalne repozytorium Dockera (GPG key, repo w sources.list lub odpowiednim katalogu dla danej dystrybucji).
• Zainstaluj pakiety docker-ce, docker-ce-cli, containerd.io (nazwy mogą się nieznacznie różnić między dystrybucjami).
• Upewnij się, że usługa docker działa i startuje z systemem: systemctl status docker, systemctl enable docker.
• Dodaj użytkownika do grupy docker, aby uniknąć ciągłego używania sudo: sudo usermod -aG docker <user>, a potem wylogowanie/logowanie.

Punkty kontrolne: docker info powinno pokazywać poprawny sterownik storage (np. overlay2) oraz brak krytycznych błędów w sekcji „Warnings”. Jeśli demon restartuje się w pętli lub storage driver jest oznaczony jako „unsupported”, nie należy budować obrazów na takim fundamencie.

Pierwszy „health check”: czy środowisko faktycznie działa

Sam fakt, że instalator przeszedł do końca, nie oznacza działającego środowiska. Minimum sanity check można sprowadzić do sekwencji:

1. docker version – sprawdzenie, czy klient widzi serwer.
2. docker info – weryfikacja storage driver, sieci, liczby obrazów/kontenerów.
3. docker run --rm hello-world – prosty kontener testowy z Docker Hub.

Jeśli hello-world nie startuje (błąd przy pobieraniu obrazu, problem z DNS, brak autoryzacji przez proxy) – dalsze kroki z własnymi obrazami skończą się identycznie lub gorzej, bo debugowanie będzie trudniejsze. Jeżeli ten test przejdzie, można założyć, że podstawowa ścieżka „CLI → daemon → sieć → registry → host” jest funkcjonalna.

Praca z gotowymi obrazami: szybki przegląd przed budową własnego

Wyszukiwanie i ocena obrazów: docker search, Docker Hub, kryteria wyboru

Zanim powstanie pierwszy własny obraz, zwykle korzysta się z tych, które już istnieją. Krytyczne jest to, jak je wybierać. Minimum narzędzi to:

• docker search <nazwa> – szybkie wyszukiwanie obrazów w domyślnym rejestrze (zwykle Docker Hub).
• Przeglądarka + Docker Hub – pełna karta obrazu z opisem, tagami, instrukcją użycia i informacjami o utrzymaniu.

Przy doborze obrazu bazowego zamiast kierować się tylko nazwą, warto zastosować checklistę:

• Status „Official Image” – obrazy oznaczone jako oficjalne (np. nginx, redis, python) mają zwykle lepszą jakość, pełniejszą dokumentację i regularne aktualizacje.
• Ostatnia aktualizacja – długa przerwa w aktualizacjach to sygnał ostrzegawczy, zwłaszcza dla języków i frameworków szybko się zmieniających.
• Liczba pobrań i gwiazdek – nie są gwarancją jakości, ale skrajnie niskie wartości przy kluczowych technologiach powinny skłonić do dodatkowego sprawdzenia.
• Dokumentacja tagów – przejrzysty opis różnic między tagami (np. -alpine, -slim, -buster) ułatwia wybór lżejszego lub bardziej kompletnego wariantu.
• Obecność przykładów – sekcja „How to use this image” z konkretnymi docker run / fragmentami Dockerfile ogranicza pole do interpretacji.

Jeśli obraz nie jest oficjalny, nie ma jasnej dokumentacji i wygląda na porzucony, to zły kandydat na fundament projektu; w takiej sytuacji lepiej poświęcić chwilę i znaleźć alternatywę nawet kosztem dodatkowego czasu konfiguracji.

Przegląd lokalnych obrazów i ich „higiena”: docker images, docker rmi

Po kilku dniach testów katalog z obrazami zaczyna rosnąć. Bez elementarnego porządku szybko trudno ustalić, co jest potrzebne, a co jest artefaktem eksperymentów. Przydają się głównie:

• docker images lub docker image ls – lista lokalnych obrazów z repozytorium, tagiem, ID, datą utworzenia i rozmiarem.
• docker rmi <image> – usunięcie obrazu (lub tagu), o ile nie używa go żaden kontener.
• docker image prune – usunięcie obrazów „dangling” (bez tagów, osierocone po przebudowach).

Punkt kontrolny: jeśli rozmiar katalogu danych Dockera idzie w dziesiątki gigabajtów, a polecenie docker images pokazuje wiele obrazów <none> lub nieużywanych od miesięcy, środowisko jest zaśmiecone. Nieużywane obrazy komplikują wybór właściwej wersji i utrudniają audyt bezpieczeństwa.

Uruchamianie gotowych obrazów: docker run z najważniejszymi opcjami

Do przetestowania obrazu z Docker Hub często wystarczy pojedyncze polecenie, ale nawet w tym scenariuszu warto stosować minimalne standardy:

• Nadanie nazwy kontenerowi: --name my-nginx zamiast anonimowych ID – ułatwia późniejszą diagnostykę.
• Mapowanie portów: -p 8080:80 przy usługach webowych – jasny sygnał, które porty są wystawione na hosta.
• Mapowanie wolumenów: -v <host_dir>:<container_dir> – np. montaż katalogu z konfiguracją.
• Tryb „detach”: -d – uruchomienie kontenera w tle, z późniejszym podglądem logów przez docker logs.

docker run --name my-nginx -p 8080:80 -d nginx:alpine

Taki wariant jasno rozgranicza obowiązki: docker run tworzy kontener o jawnej nazwie, port 8080 na hoście kieruje na port 80 w kontenerze, a logi można sprawdzić bez „uwiązania” terminala. Jeśli ktoś używa wyłącznie docker run nginx bez parametrów, trudno później odnaleźć, który proces odpowiada za konkretny ruch na porcie.

Analiza i introspekcja działającego kontenera: docker ps, inspect, top

Sam start kontenera to dopiero początek. Do rzetelnej diagnostyki potrzebne są minimum następujące narzędzia:

• docker ps – lista działających kontenerów (z -a także zatrzymane). Szybki sposób na weryfikację, czy kontener nadal działa, czy zakończył się błędem.
• docker inspect <container> – szczegółowa konfiguracja kontenera: zmienne środowiskowe, sieci, mounty, użyty obraz, parametry startowe.
• docker top <container> – procesy działające wewnątrz kontenera.

Punkt kontrolny: jeśli kontener kończy się natychmiast po starcie, docker ps -a oraz docker logs powinny być pierwszym miejscem, do którego się zagląda. Z kolei docker inspect pozwala odtworzyć sposób, w jaki kontener został uruchomiony, co bywa kluczowe przy próbie odtworzenia błędu w innym środowisku.

Pierwszy Dockerfile: struktura, instrukcje i sensowny przykład

Rola Dockerfile w procesie budowy obrazu

Dockerfile to deklaratyczny opis tego, jak zbudować obraz. Zamiast klikać w systemie operacyjnym lub wpisywać komendy ręcznie, zapisuje się je w postaci instrukcji, które można wersjonować w repozytorium. Praktycznie oznacza to, że:

• każde środowisko deweloperskie i CI może zbudować ten sam obraz z tych samych źródeł,
• historia zmian w Dockerfile jest częścią historii projektu (PR-y, code review),
• proces budowy nie jest „wiedzą plemienną” jednego administratora.

Jeśli obraz jest budowany ręcznie na jednym serwerze, a potem eksportowany i kopiowany, nie jest to powtarzalny proces. Dockerfile jest minimum transparentności i audytowalności.

Podstawowe instrukcje: FROM, RUN, COPY, WORKDIR, CMD, EXPOSE

Większość prostych obrazów składa się z kilku kluczowych instrukcji. Każda z nich tworzy nową warstwę obrazu, więc ich kolejność i treść ma znaczenie dla rozmiaru, szybkości budowania i cache’owania.

• FROM – wybór obrazu bazowego, np. FROM python:3.11-slim. To fundament, na którym budowane są kolejne warstwy.
• RUN – wykonanie polecenia w czasie budowy, np. instalacja pakietów systemowych. Wszystko, co tu powstanie, trafi do gotowego obrazu.
• COPY / ADD – skopiowanie plików z kontekstu budowy (katalogu, z którego wywołano docker build) do systemu plików w obrazie.
• WORKDIR – ustawienie katalogu roboczego dla kolejnych instrukcji RUN, CMD, ENTRYPOINT itd.
• CMD – domyślne polecenie uruchamiane przy starcie kontenera, jeśli użytkownik nie poda własnego.
• EXPOSE – deklaracja portu używanego przez aplikację w kontenerze (informacja dokumentacyjna dla innych narzędzi).

Punkt kontrolny: jeśli Dockerfile jest pełen losowych RUN instalujących zależności bez ładu, a CMD jest niejasne lub nieobecne, obraz prawdopodobnie będzie mało przewidywalny i trudny w utrzymaniu.

Struktura sensownego Dockerfile na przykładzie prostej aplikacji

Praktyczny przykład pomaga szybko wyłapać zależności między instrukcjami. Załóżmy prostą aplikację w Pythonie (serwer HTTP), którą chcemy uruchomić w kontenerze. Prosty, ale uporządkowany Dockerfile może wyglądać tak:

FROM python:3.11-slim

# Ustawienie katalogu roboczego
WORKDIR /app

# Kopiowanie plików z zależnościami
COPY requirements.txt .

# Instalacja zależności aplikacji
RUN pip install --no-cache-dir -r requirements.txt

# Kopiowanie reszty kodu
COPY . .

# Deklaracja portu używanego przez aplikację
EXPOSE 8000

# Domyślne polecenie uruchamiające aplikację
CMD ["python", "app.py"]

Taka struktura wprowadza kilka dobrych praktyk od razu:

• kopia requirements.txt przed resztą kodu – zmiana w kodzie nie wymusza ponownej instalacji zależności, co poprawia wykorzystanie cache,
• jawny WORKDIR – pozostałe instrukcje nie muszą używać ścieżek absolutnych,
• zastosowanie CMD w formie listy (exec form) – unika problemów z powłoką i sygnałami.

Jeśli projekt już na starcie ma Dockerfile z migającymi ścieżkami, przypadkowo kopiowanym katalogiem .git i brakiem rozdziału między zależnościami a kodem, w kolejnych iteracjach będzie tylko trudniej utrzymać porządek.

Instrukcje wspierające: ENV, ARG, ENTRYPOINT, VOLUME

Poza zestawem podstawowym szybko pojawia się potrzeba parametryzacji obrazu. Do tego służą m.in.:

• ENV – ustawienie zmiennych środowiskowych w obrazie, np. ENV PYTHONDONTWRITEBYTECODE=1, ENV PYTHONUNBUFFERED=1. Te wartości będą domyślnie widoczne w kontenerze.
• ARG – zmienne używane na etapie budowy (build-time), np. ARG APP_ENV=dev. Nie są automatycznie dostępne w uruchomionym kontenerze.

Parametry budowy i uruchomienia: praktyczne użycie ENV, ARG, ENTRYPOINT i VOLUME

Prosty Dockerfile szybko przestaje wystarczać, gdy aplikacja ma kilka środowisk (dev/test/prod) i różne sposoby uruchomienia. Minimalny, ale uporządkowany zestaw mechanizmów do parametryzacji daje kontrolę nad zachowaniem obrazu bez kopiowania niemal identycznych plików Dockerfile.

• ENV – konfiguracja „wypalona” w obrazie. Przydaje się do ustawień technicznych, które praktycznie się nie zmieniają, np.:

  ENV PYTHONDONTWRITEBYTECODE=1 
      PYTHONUNBUFFERED=1

  Jeśli te wartości trzeba będzie zmienić per środowisko, lepszym miejscem są zmienne podawane przy docker run lub compose.

• ARG – dane dostępne tylko podczas budowy. Typowe zastosowanie to wybór wariantu obrazu lub wstrzyknięcie numeru wersji:

  ARG APP_ENV=dev
  ENV APP_ENV=${APP_ENV}
  
  ARG APP_VERSION=local
  LABEL app.version=${APP_VERSION}

  Taki wzorzec pozwala na oznaczanie obrazów metadanymi bez „ręcznego” dopisywania wersji w różnych miejscach.

• ENTRYPOINT – główne polecenie, którego użytkownik zwykle nie nadpisuje, np. skrypt startowy:

  ENTRYPOINT ["python", "app.py"]
  CMD ["--host=0.0.0.0", "--port=8000"]

  W tym układzie ENTRYPOINT definiuje „program”, a CMD – domyślne argumenty, które użytkownik może łatwo zmienić.

• VOLUME – deklaracja punktu montowania danych, które mają przetrwać restart kontenera, np.:

  VOLUME ["/app/data"]

  Takie wskazanie to sugestia dla użytkownika, gdzie przechowywać trwałe dane lub logi.

Punkt kontrolny: jeśli w Dockerfile ENV miesza ustawienia stałe i środowiskowe (np. hasła, URL-e baz danych), a ENTRYPOINT jest skryptem o niejasnej zawartości, obraz będzie trudny w audycie i rekonfiguracji. Rozdzielenie tego, co stałe (ENV, LABEL), od tego, co zmienne (ARG, zmienne przy docker run) znacząco upraszcza śledzenie wpływu zmian.

Typowe antywzorce w Dockerfile i jak ich unikać

Już na poziomie pierwszego obrazu można wprowadzić błędy, które na małej aplikacji są niewidoczne, ale przy większym projekcie powodują problemy z bezpieczeństwem i rozmiarem. Kilka powtarzalnych sygnałów ostrzegawczych:

• Użycie „latest” bez powodu:

  FROM node:latest

  Taki zapis sprawia, że kolejne buildy mogą bazować na innym systemie, innym Node i innym zestawie bibliotek. Minimum to jawna wersja, np. node:20-alpine.

• Łączenie wielu niepowiązanych operacji w jednym RUN bez kontroli:

  RUN apt-get update && apt-get install -y curl git vim python3

  Instalacja narzędzi deweloperskich (vim, git) w obrazie produkcyjnym to klasyczny nadmiar. Przy sensownym podziale lepiej mieć obraz „runtime” odchudzony z niepotrzebnych pakietów.

• Kopiowanie całego kontekstu bez .dockerignore:

  COPY . .

  Bez pliku .dockerignore w obrazie może skończyć np. katalog .git, artefakty CI czy tajne pliki konfiguracyjne z lokalnego środowiska.

• Brak użytkownika nieuprzywilejowanego – wszystko jako root:

  # brak USER, aplikacja działa jako root

  To ułatwia eksploity i wyciek danych, zwłaszcza jeśli obraz jest używany w środowisku o słabszej izolacji.

Jeśli Dockerfile zawiera nieprecyzyjny FROM ...:latest, brak .dockerignore i uruchamia aplikację jako root, to już na starcie środowisko traci na powtarzalności i bezpieczeństwie. Im wcześniej te sygnały zostaną wychwycone, tym mniej zmian trzeba będzie później nadrabiać.

Budowanie obrazu krok po kroku: docker build bez czarnej magii

Rola kontekstu budowy i pliku .dockerignore

Komenda docker build wysyła do demona Dockera tzw. kontekst budowy – cały katalog, z którego build jest wywoływany (z uwzględnieniem .dockerignore). To kluczowy element, bo przeładowanie do demona tysięcy niepotrzebnych plików spowalnia build i zwiększa ryzyko wycieku danych.

Minimalny .dockerignore w projekcie aplikacyjnym powinien zawierać przynajmniej:

.git
.gitignore
__pycache__
*.pyc
node_modules
dist
build
*.log
.env
.env.*
Dockerfile*

Takie filtrowanie sprawia, że Docker widzi tylko to, co ma trafić do obrazu – kod, manifesty zależności, konfigurację potrzebną w runtime. Build jest szybszy, a przypadkowa obecność haseł w plikach lokalnych nie kończy się „wypaleniem” ich w obrazie.

Punkt kontrolny: jeśli docker build „mieli” przez kilkadziesiąt sekund przy kroku „Sending build context to Docker daemon…”, a log pokazuje dziesiątki lub setki MB kontekstu, .dockerignore jest zbyt ubogi lub nie istnieje.

Podstawowe wywołanie docker build i nazewnictwo obrazów

Najprostszy build można uruchomić z katalogu, w którym leży Dockerfile:

docker build -t myapp:dev .

Kluczowe elementy, które warto ustalić jako standard w zespole:

• -t / --tag – nazwa i wersja obrazu w formacie repozytorium:tag, np. app-backend:1.0.0, company/app-frontend:dev. Spójne nazewnictwo ułatwia identyfikację i automatyzację w CI.
• kontekst – ostatni argument (zwykle .), czyli katalog, z którego Docker bierze pliki. Zmiana kontekstu zmienia to, co jest widoczne dla COPY / ADD.
• lokalizacja Dockerfile – jeśli plik ma inną nazwę lub leży w innym miejscu:

  docker build -f docker/Dockerfile.prod -t myapp:prod .

  To przydaje się, gdy istnieje kilka wariantów obrazu (np. dev/prod) lub osobny Dockerfile dla testów end-to-end.

Jeśli obrazy mają nazwy w stylu test, new, nowy2, a tagi są przypadkowe lub domyślne (latest), audyt tego, co faktycznie zostało wdrożone, jest w praktyce niewykonalny. Stały schemat nazewniczy to minimum umożliwiające śledzenie wersji.

Warstwy, cache i ich praktyczne wykorzystanie

Każda instrukcja w Dockerfile tworzy warstwę obrazu. Docker cache’uje te warstwy i przy kolejnym buildzie wykorzystuje je, jeśli nic się nie zmieniło w danym kroku oraz w poprzednich. Poprawne uporządkowanie instrukcji ma bezpośredni wpływ na czas budowy.

Przykład korzystającego z cache Dockerfile:

FROM python:3.11-slim

WORKDIR /app

# Zależności - zmieniają się rzadziej niż kod
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Kod - zmienia się częściej
COPY . .

CMD ["python", "app.py"]

Jeśli zmieni się wyłącznie plik app.py, przy kolejnym buildzie Docker użyje cache dla warstw z FROM, WORKDIR, COPY requirements.txt i RUN pip install..., a przebuduje jedynie warstwę z COPY . .. To skraca build do kilku sekund.

Przeciwny przykład – Dockerfile łamiący cache:

FROM python:3.11-slim

WORKDIR /app

COPY . .
RUN pip install --no-cache-dir -r requirements.txt

CMD ["python", "app.py"]

Zmiana w dowolnym pliku projektu (nawet w dokumentacji) powoduje przebudowę warstwy COPY . ., a przez to również ponowną instalację zależności. Przy większych aplikacjach to różnica rzędu minut w każdym buildzie.

Punkt kontrolny: jeśli każdy build wymaga pobrania i instalacji wszystkich zależności od zera, a nie ma ku temu uzasadnienia (np. celowe --no-cache w CI), kolejność instrukcji w Dockerfile jest najprawdopodobniej nieoptymalna.

Diagnostyka procesu budowy: logi, tryb szczegółowy i typowe błędy

Podczas budowy obrazu pierwszym źródłem informacji są standardowe logi z docker build. Przy bardziej złożonych przypadkach przydatny staje się tryb szczegółowy:

docker build --progress=plain --no-cache -t myapp:debug .

--progress=plain wyłącza „ładne” formatowanie na rzecz surowych logów, w których dokładniej widać wykonanie poszczególnych kroków. --no-cache wymusza pełną przebudowę – przydatne, gdy istnieje podejrzenie, że cache wykorzystuje „stare” warstwy wbrew oczekiwaniom.

Kilka powtarzających się klas błędów:

• Błędy sieciowe i brak pakietów – problemy przy apt-get, pip, npm. Warto sprawdzić:
  • czy repozytoria są aktualne (apt-get update przed apt-get install),
  • czy proxy/HTTPS w danym środowisku nie filtruje zapytań.
• Brak pliku przy COPY/ADD:

  failed to compute cache key: "/app/requirements.txt" not found

  Taki komunikat często oznacza, że plik znajduje się poza kontekstem budowy lub został wykluczony przez .dockerignore.

• Błędy uprawnień – np. przy uruchamianiu skryptu jako nieuprzywilejowany użytkownik bez stosownych praw do katalogu roboczego.

Jeśli docker build nie jest w stanie powtarzalnie zakończyć się sukcesem (raz działa, raz nie) bez zmiany plików, źródło problemu zwykle leży w zależnościach zewnętrznych (niestabilne repozytoria) albo w nadmiernym wykorzystywaniu losowości w skryptach RUN. Stabilność procesu budowy jest tak samo istotna jak stabilność samej aplikacji.

Tagowanie i wersjonowanie obrazów dla różnych środowisk

Gdy pierwszy obraz zaczyna „żyć” w kilku środowiskach (dev, staging, produkcja), nie wystarczy już pojedynczy tag. Spójny, prosty schemat wersjonowania ogranicza liczbę pomyłek przy wdrożeniach.

Przykładowa strategia tagów:

• tag semantyczny – spójny z wersją aplikacji: 1.3.0, 1.3.1 itd.,
• tag środowiskowy – dev, staging, prod,
• tag pomocniczy – np. skrót commita: 1.3.0-abc1234.

Build można opisać kilkoma tagami jednocześnie:

docker build 
  -t registry.example.com/myapp:1.3.0 
  -t registry.example.com/myapp:1.3.0-abc1234 
  -t registry.example.com/myapp:dev 
  .

Punkt kontrolny: jeśli w procesie wdrożeniowym jedynym istotnym tagiem jest latest, niemożliwe jest szybkie odtworzenie, który obraz faktycznie działa na produkcji. W razie awarii powrót do poprzedniej wersji staje się loterią zamiast kontrolowaną operacją.

Od obrazu do uruchomienia: docker run na świeżo zbudowanym obrazie

Po zbudowaniu obrazu logicznym krokiem jest jego uruchomienie lokalnie z parametrami jak najbardziej zbliżonymi do tych z przyszłego środowiska docelowego. Pozwala to wyłapać niezgodności konfiguracji, zanim obraz trafi do rejestru.

Załóżmy, że zbudowany został obraz myapp:dev, który słucha na porcie 8000. Typowe uruchomienie testowe:

docker run --rm 
  --name myapp-dev 
  -p 8000:8000 
  -e APP_ENV=dev 
  myapp:dev

• --rm – automatyczne usunięcie kontenera po zatrzymaniu; ogranicza bałagan przy częstych testach.
• -e – wstrzyknięcie zmiennych środowiskowych, które nie są „wypalone” w obrazie, np. APP_ENV, LOG_LEVEL.
• -p – mapowanie portu kontenera na port hosta.

Dla aplikacji korzystającej z plikowej bazy danych lub lokalnego storage rozsądne jest też użycie wolumenów:

Najczęściej zadawane pytania (FAQ)

Co to jest obraz Docker i czym różni się od kontenera?

Obraz Docker to szablon systemu plików z metadanymi: zawiera aplikację, biblioteki, konfigurację oraz polecenie startowe. Jest niezmienny – nie „żyje” w czasie uruchomienia, tylko służy jako wzorzec do tworzenia kontenerów. Zmiany wprowadza się przez zbudowanie nowego obrazu, a nie przez edycję istniejącego.

Kontener to uruchomiony proces na bazie obrazu, odizolowany za pomocą namespaces i cgroups. Ma własny system plików, sieć i konfigurację runtime, ale współdzieli kernel z hostem. Modyfikacje w kontenerze nie dotykają obrazu – po usunięciu kontenera obraz pozostaje niezmieniony.

Punkt kontrolny: jeśli zmiana ma dotyczyć „wersji aplikacji”, robisz nowy obraz; jeśli chodzi o „instancję aplikacji” (kilka kopii, restart, inne porty), operujesz na kontenerach.

Kiedy użycie Dockera ma sens, a kiedy jest na wyrost?

Docker ma największy sens, gdy głównym problemem jest powtarzalność środowiska i konfliktujące zależności: kilku developerów pracuje nad tym samym projektem, w CI trzeba odpalać bazy i serwisy pomocnicze, a aplikacja ma trafić na różne serwery. W takich przypadkach kontenery ograniczają „u mnie działa” i przyspieszają cykl zmian.

Jest natomiast narzędziem na wyrost w małych, jednorazowych projektach (np. pojedynczy skrypt uruchamiany lokalnie), tam gdzie środowisko jest stabilne i proste albo w firmach z bardzo restrykcyjnymi politykami bezpieczeństwa blokującymi Docker Engine. Dodatkowym sygnałem ostrzegawczym jest zespół bez żadnego doświadczenia w konteneryzacji, który chce „wrzucić wszystko w Dockera” bez zrozumienia podstaw.

Jeśli problemem są realne konflikty zależności i potrzeba spójnego setupu dla wielu osób lub serwerów – Docker zwykle pomaga. Jeśli projekt jest mały, jednorazowy i lokalny, może wprowadzić więcej procedur niż faktycznej wartości.

Czym różni się kontener Docker od maszyny wirtualnej (VM)?

Maszyna wirtualna emuluje cały system: od sprzętu, przez kernel, po system operacyjny i aplikacje. Kontener współdzieli kernel hosta, ale ma własną przestrzeń użytkową (system plików, procesy, sieć). Dlatego VM startuje wolniej, zużywa więcej pamięci i wymaga pełnej administracji systemem operacyjnym wewnątrz.

Kontener startuje zwykle w sekundy i nie dubluje całego systemu operacyjnego – host przechowuje wspólne warstwy obrazów tylko raz. Zmiana wersji np. Postgresa to zbudowanie lub pobranie nowego obrazu i restart kontenera, a nie reinstalacja całej maszyny.

Jeśli potrzebujesz pełnej izolacji (inne jądro, inny system operacyjny, wysokie wymagania bezpieczeństwa) – przewagę ma VM. Jeśli chcesz lekkich, powtarzalnych środowisk aplikacyjnych na wspólnym kernelu – kontenery są bardziej efektywne.

Jak sprawdzić, czy Docker jest poprawnie zainstalowany i działa?

Minimum to trzy komendy diagnostyczne: docker version, docker info i docker <komenda> --help. Jeśli docker version zwraca dane klienta, ale sekcja „Server” pokazuje błąd, demon Dockera nie działa lub jest niedostępny – to pierwszy sygnał ostrzegawczy.

docker info pokazuje szczegóły środowiska: liczbę obrazów i kontenerów, używany sterownik storage, sieci, dostępne zasoby. Przy każdym problemie z budowaniem lub uruchamianiem kontenerów jest to główne źródło prawdy o stanie hosta. Dodatkowo, docker run --help pozwala szybko zweryfikować składnię i opcje zamiast kopiować przypadkowe przykłady z sieci.

Jeśli docker version i docker info nie działają, nie ma sensu debugować Dockerfile ani parametrów docker run – najpierw trzeba ustabilizować sam Docker Engine.

Co to jest rejestr Docker, tag i warstwy obrazu?

Rejestr (registry) to miejsce przechowywania obrazów, na przykład Docker Hub, GitHub Container Registry albo prywatny serwer w firmie. Docker pobiera obrazy z rejestru (docker pull) i wysyła do niego nowe wersje (docker push). To centralny punkt kontrolny, jeśli obrazy mają być współdzielone w zespole lub w CI.

Tag to etykieta przypięta do konkretnej wersji obrazu, np. python:3.11-slim czy myapp:1.0.0. Nie jest osobnym obrazem, tylko referencją do zestawu warstw. Obraz składa się z warstw (layers) tworzonych przez kolejne instrukcje Dockerfile (FROM, RUN, COPY). Warstwy są cache’owane i współdzielone: jeśli kilka obrazów bazuje na tym samym python:3.11-slim, host przechowuje tę bazę tylko raz.

Jeśli obrazy szybko „zjadają” dysk, pierwszym krokiem audytu jest sprawdzenie, czy nie dublujesz tych samych baz i czy tagi są używane sensownie, np. zamiast nieskończonej liczby anonimowych wersji typu latest.

Do czego Docker sprawdza się najlepiej w praktyce?

Typowe, sprawdzone zastosowania to: wspólne środowiska developerskie (jeden zestaw kontenerów dla całego zespołu), uruchamianie zależnych serwisów w pipeline CI (bazy, cache, message brokery), małe usługi i narzędzia CLI pakowane jako obraz oraz reprodukowalne debugowanie błędów na podstawie konkretnej wersji obrazu i konfiguracji.

Dobrym przykładem jest projekt z aplikacją webową i PostgresQL: każdy developer pobiera te same obrazy, uruchamia kontenery jednym poleceniem i dostaje identyczne środowisko. Testy w CI też korzystają z tych samych obrazów, więc różnice między „dev”, „test” i „prod” są kontrolowane, a nie przypadkowe.

Jeśli kilka osób ma korzystać z tego samego projektu lub środowisko będzie odtwarzane wielokrotnie (development, testy, produkcja), Docker jest praktycznie standardem jakości. Jeśli projekt ma jednego użytkownika i jedno środowisko, zysk z konteneryzacji jest dużo mniej oczywisty.

Jakie pojęcia i narzędzia Docker muszę opanować na absolutny start?

Minimum pojęciowe to: obraz (image), kontener (container), rejestr (registry), tag i warstwa obrazu (layer). Bez tego każdy kolejny krok będzie mechanicznym kopiowaniem przykładów, a nie świadomym projektowaniem środowiska. Z narzędzi – Docker Engine (demon), Docker CLI oraz ewentualnie Docker Desktop jako „opakowanie” dla Windows/macOS.

Dla początkującego praktyczny zestaw punktów kontrolnych wygląda tak:

• rozumiesz, że obraz to wzorzec, kontener to działający proces na jego podstawie,
• umiesz zinterpretować wynik docker version i docker info,
• odróżniasz tag latest od wersjonowanych tagów typu 1.0.0,