Docker od środka

Większość problemów z Dockerem nie bierze się z nieznajomości komend. Bierze się z błędnego modelu w głowie: „kontener to lekka maszyna wirtualna”, „RUN rm zmniejsza obraz”, „EXPOSE otwiera port”. Każdy rozdział tłumaczy jeden mechanizm, pokazuje go na klikalnym diagramie i celowo go psuje (przycisk 💥), żebyś zobaczył objaw, zanim spotkasz go na produkcji.

Największy nacisk leży na budowaniu obrazów: Dockerfile, kontekst, cache warstw, multi-stage, BuildKit, sekrety, wiele platform. Reszta — runtime, sieci, dane, Compose, rejestry, bezpieczeństwo — jest po to, żeby obraz miał sens w praktyce.

Kompendium ma poziomy. Rozdziały i bloki mają znaczek — L1 podstawy, L2 praktyk, L3 ekspert. Głębokość wybierasz przełącznikiem w lewym dolnym rogu; głębszy materiał chowa się, dopóki go nie zechcesz. Mapa poniżej skacze do dowolnego rozdziału i odhacza przeczytane.

Maszyna wirtualna emuluje sprzęt i uruchamia własne jądro systemu. Kontener niczego nie emuluje. To zwykły proces na jądrze hosta, któremu jądro pokazuje „okrojony świat”: własne drzewo procesów, własny interfejs sieciowy, własny system plików. Robią to dwa mechanizmy jądra Linux.

• Namespaces — izolują to, co proces widzi: pid (procesy), net (sieć), mnt (punkty montowania), uts (hostname), ipc, user (mapowanie UID).
• Control groups (cgroups) — ograniczają to, ile proces może zużyć: pamięć, CPU, I/O, liczbę procesów.

Docker to architektura klient–serwer. Polecenie docker to klient. Wysyła żądania przez REST API (domyślnie na gniazdo Unix /var/run/docker.sock) do demona dockerd. Demon zarządza obrazami, sieciami i wolumenami, a samo uruchamianie kontenerów deleguje do containerd. Ten z kolei używa runtime’u OCI runc, który tworzy namespaces i cgroups i odpala proces.

Obraz to uporządkowany stos warstw tylko do odczytu plus konfiguracja (domyślne polecenie, zmienne, użytkownik…). Każda warstwa to zestaw zmian w systemie plików względem poprzedniej: dodane, zmienione i usunięte pliki. Sterownik storage (klasycznie overlay2; w świeżych instalacjach Docker Engine 29+ domyślnie containerd image store, również oparty na overlayfs) nakłada je na siebie i pokazuje jako jeden system plików.

Uruchomienie kontenera dodaje na wierzch cienką warstwę zapisu. Wszystkie zmiany kontenera lądują tylko tam. Usunięcie kontenera usuwa tę warstwę — warstwy obrazu zostają nietknięte i współdzielone przez wszystkie kontenery z tego obrazu.

Kontener żyje tak długo, jak jego główny proces (PID 1 w namespace kontenera). Gdy proces się kończy, kontener przechodzi w stan exited i zachowuje kod wyjścia. Zatrzymany kontener nadal istnieje — razem z warstwą zapisu i logami — dopóki go nie usuniesz.

Dockerfile to plik tekstowy z instrukcjami wykonywanymi po kolei. docker build wysyła go razem z kontekstem (zwykle bieżący katalog) do buildera BuildKit. BuildKit jest domyślnym builderem w Docker Desktop i Docker Engine. Instrukcje dzielą się na dwie grupy: takie, które zmieniają system plików (RUN, COPY, ADD) i tworzą warstwę z zawartością, oraz takie, które zmieniają tylko konfigurację obrazu (ENV, CMD, LABEL, EXPOSE…). Te drugie w docker image history mają rozmiar 0 B.

W docker build -t app . kropka to kontekst — zbiór plików, do których builder ma dostęp. COPY widzi wyłącznie pliki z kontekstu; COPY ../secret . nie zadziała. Kontekst może być lokalnym katalogiem, adresem repozytorium Git, archiwum tar albo pustym kontekstem (Dockerfile ze stdin: docker build -).

Plik .dockerignore w katalogu głównym kontekstu wyklucza ścieżki z kontekstu. Składnia przypomina .gitignore: wzorce, ** dla dowolnej głębokości, ! dla wyjątków. Dla konkretnego Dockerfile możesz mieć osobny plik, np. build.Dockerfile.dockerignore obok build.Dockerfile.

# .dockerignore — przykład dla aplikacji Node.js
.git
node_modules
dist
**/*.log
.env
.env.*
!.env.example
Dockerfile*
.dockerignore

Builder przy każdej instrukcji sprawdza, czy ma w cache wynik dla identycznego wejścia. Jeśli tak — używa go (CACHED). Jeśli nie — wykonuje krok i wszystkie kolejne kroki też, bo ich wejściem jest zmieniona warstwa. Reguły:

• RUN — klucz to tekst polecenia (i warstwa pod nim). Builder nie wie, że apt-get update dałoby dziś inny wynik.
• COPY / ADD — klucz to suma kontrolna zawartości i metadanych kopiowanych plików. Sam czas modyfikacji (mtime) nie jest brany pod uwagę.
• ARG — zmiana wartości unieważnia cache przy pierwszym użyciu zmiennej, nie przy jej deklaracji. Zmiana wartości ENV w Dockerfile to zmiana samej instrukcji, więc miss zaczyna się od tej linii.

# syntax=docker/dockerfile:1
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./   # zmienia się rzadko
RUN npm ci                                # drogi krok — chroniony przez cache
COPY . .                                  # zmienia się często
CMD ["node", "src/app.js"]

Każdy RUN to osobna warstwa. Warstwa przechowuje różnicę względem poprzedniej. Jeśli w jednym RUN pobierzesz 300 MB, a w kolejnym je usuniesz, obraz dalej zawiera 300 MB — usunięcie tylko zasłania pliki (whiteout). Sprzątaj w tym samym RUN, w którym śmiecisz.

Shell form, exec form i heredoki

Shell form (RUN npm ci) uruchamia polecenie przez /bin/sh -c, więc działają zmienne, potoki i &&. Exec form (RUN ["npm","ci"]) to tablica JSON uruchamiana bez powłoki — bez podstawiania zmiennych typu $HOME. Tablica musi używać cudzysłowów podwójnych; z pojedynczymi Docker potraktuje ją jak shell form.

# heredoc (Dockerfile 1.4+): wiele poleceń, jedna warstwa, czytelnie
RUN <<EOF
set -e
apt-get update
apt-get install -y --no-install-recommends curl ca-certificates
rm -rf /var/lib/apt/lists/*
EOF

ENTRYPOINT określa program, który kontener zawsze uruchamia. CMD dostarcza domyślne argumenty — albo całe domyślne polecenie, gdy ENTRYPOINT nie istnieje. Argumenty podane w docker run obraz arg1 arg2 zastępują CMD, ale nie ENTRYPOINT. Najczęstszy wzorzec: ENTRYPOINT ["app"] + CMD ["--help"].

docker stop wysyła do głównego procesu sygnał stopu (domyślnie SIGTERM, zmienisz go przez STOPSIGNAL) i czeka. Dla kontenerów Linux domyślny limit to 10 sekund; po nim leci SIGKILL. Jeśli stop zawsze trwa równo 10 sekund, twoja aplikacja nie dostaje SIGTERM albo go ignoruje.

Dwie typowe przyczyny. Pierwsza: shell form (CMD node app.js). PID 1 to wtedy /bin/sh -c, który nie przekazuje sygnałów dziecku. Druga: proces z PID 1 jest w Linuksie traktowany specjalnie — jądro nie stosuje domyślnej akcji „zakończ” dla sygnałów, na które PID 1 nie ma handlera. Aplikacja bez handlera SIGTERM po prostu go nie zauważy.

ARG istnieje tylko w czasie budowania, ENV — w czasie budowania i w każdym kontenerze z obrazu. Zakresy mają reguły, które łatwo przeoczyć:

• ARG przed pierwszym FROM jest w zakresie globalnym — działa tylko w liniach FROM. Żeby użyć go w etapie, napisz w nim ponownie ARG NAZWA (bez wartości).
• ARG w etapie żyje do końca tego etapu.
• ENV o tej samej nazwie co ARG wygrywa z nim.
• BuildKit udostępnia automatyczne ARG platformy: TARGETPLATFORM, TARGETOS, TARGETARCH, BUILDPLATFORM… W etapie trzeba je zadeklarować (ARG TARGETARCH).

ARG NODE_VER=22
FROM node:${NODE_VER}-slim AS build   # globalny ARG działa w FROM
ARG NODE_VER                          # ...a w etapie trzeba go powtórzyć
RUN echo "building on node $NODE_VER"
FROM node:${NODE_VER}-slim AS runtime
ENV PORT=8080                         # trafi do kontenera

Kompilator, nagłówki, cache menedżera pakietów i testy są potrzebne do zbudowania aplikacji, ale nie do jej uruchomienia. Multi-stage build dzieli Dockerfile na etapy: każdy FROM zaczyna nowy etap, a COPY --from=etap przenosi tylko wybrane artefakty. Obraz wynikowy to ostatni etap (albo ten wskazany przez --target) — reszta nie trafia do obrazu.

# syntax=docker/dockerfile:1
FROM golang:1.23 AS build
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o /out/app ./cmd/app

FROM build AS test
RUN go test ./...

FROM gcr.io/distroless/static-debian12 AS runtime
COPY --from=build /out/app /app
USER nonroot:nonroot
ENTRYPOINT ["/app"]

Klasyczny builder wykonywał Dockerfile linia po linii. BuildKit zamienia go w graf zależności: wykrywa i pomija nieużywane etapy, buduje niezależne etapy równolegle i przesyła z kontekstu tylko pliki, których build używa. Do tego dochodzą RUN --mount — tymczasowe montowania widoczne tylko podczas jednego kroku i nie zapisywane w warstwie.

RUN --mount=type=cache,target=/root/.npm \
    npm ci
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    apt-get update && apt-get install -y --no-install-recommends gcc
RUN --mount=type=bind,target=. \
    go build -o /out/app ./cmd/app

Build często potrzebuje sekretu: tokenu do prywatnego rejestru npm, klucza SSH do prywatnego repo, poświadczeń chmurowych. Każdy sposób, który zapisuje sekret w warstwie lub metadanych, publikuje go razem z obrazem. Dobre sposoby są dwa: secret mount i SSH mount.

# Dockerfile
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
    npm ci
RUN --mount=type=secret,id=API_TOKEN,env=API_TOKEN \
    ./fetch-assets.sh
RUN --mount=type=ssh \
    git clone git@github.com:org/private.git

# CLI
docker build --secret id=npmrc,src=$HOME/.npmrc \
             --secret id=API_TOKEN,env=API_TOKEN \
             --ssh default .

Każdy pakiet w obrazie to megabajty do pobrania i potencjalne podatności do łatania. Wybór obrazu bazowego to największa pojedyncza decyzja o rozmiarze i powierzchni ataku.

Laptop z Apple Silicon to linux/arm64, typowy serwer w chmurze — linux/amd64. Obraz wieloplatformowy to indeks obrazów (manifest list): jeden tag wskazuje kilka manifestów, po jednym na platformę. docker pull sam wybiera manifest pasujący do hosta.

Klasyczny storage obrazów (domyślny w starszych wersjach Docker Engine; nowsze wersje domyślnie używają containerd image store) nie przechowuje obrazów wieloplatformowych. Potrzebujesz containerd image store albo buildera z driverem docker-container (wtedy wynik trzeba jawnie wypchnąć lub załadować).

# cross-kompilacja: etap build działa natywnie na platformie buildera
FROM --platform=$BUILDPLATFORM golang:1.23 AS build
ARG TARGETOS TARGETARCH
WORKDIR /src
COPY . .
RUN GOOS=$TARGETOS GOARCH=$TARGETARCH go build -o /out/app .

FROM alpine:3.20
COPY --from=build /out/app /app
ENTRYPOINT ["/app"]

# docker buildx build --platform linux/amd64,linux/arm64 -t reg/app:1.0 --push .

Eksport cache — szybki build w CI

Runner CI startuje zwykle z pustym builderem. Cache można wyeksportować i zaimportować przez --cache-to / --cache-from.

docker buildx build \
  --cache-from type=registry,ref=reg/app:buildcache \
  --cache-to   type=registry,ref=reg/app:buildcache,mode=max \
  -t reg/app:1.0 --push .

group "default" { targets = ["api", "worker"] }
target "api" {
  context   = "."
  target    = "runtime"
  platforms = ["linux/amd64", "linux/arm64"]
  tags      = ["reg/api:1.0"]
}

Warstwa zapisu kontenera znika razem z nim. Dane, które mają przeżyć kontener, trzymasz poza nią. Docker ma trzy rodzaje montowań:

Każdy kontener ma własny namespace sieciowy, więc localhost w kontenerze to sam kontener, nie host. Domyślnie kontener trafia do sieci bridge. Kluczowa różnica: sieć zdefiniowana przez użytkownika (docker network create app) daje automatyczny DNS — kontenery widzą się po nazwie. Domyślny bridge tego nie robi.

Bez limitów kontener może użyć tyle pamięci i CPU, ile da jądro hosta. Limity ustawiasz flagami docker run, które tłumaczą się na cgroups. Gdy proces przekroczy twardy limit pamięci, jądro zabija go (OOM kill) — zwykle zobaczysz kod 137 i OOMKilled: true w docker inspect. Polityka restartu decyduje, co dalej.

HEALTHCHECK --interval=30s --timeout=3s --start-period=20s --retries=3 \
  CMD curl -fsS http://localhost:8080/health || exit 1

Compose opisuje aplikację wielokontenerową w pliku YAML (compose.yaml). Każdy serwis to kontener (lub kilka replik) z obrazem albo sekcją build. Compose automatycznie tworzy sieć dla projektu, więc serwisy widzą się po nazwach — api łączy się z db:5432.

services:
  api:
    build: { context: ., target: dev }
    ports: ["127.0.0.1:8080:8080"]
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
    depends_on:
      db: { condition: service_healthy }
      migrate: { condition: service_completed_successfully }
    develop:
      watch:
        - { action: sync, path: ./src, target: /app/src }
        - { action: rebuild, path: package.json }
  migrate:
    build: .
    command: ["npm", "run", "migrate"]
    depends_on: { db: { condition: service_healthy } }
  db:
    image: postgres:17
    environment: { POSTGRES_USER: app, POSTGRES_PASSWORD: app }
    volumes: ["pgdata:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      retries: 10
  adminer:
    image: adminer
    profiles: ["tools"]
volumes:
  pgdata:

Pełna nazwa obrazu to [rejestr/][namespace/]repozytorium[:tag|@digest]. Bez rejestru Docker używa Docker Hub (docker.io), a oficjalne obrazy żyją w namespace library — dlatego debian to w rzeczywistości docker.io/library/debian:latest. Bez tagu Docker przyjmuje latest.

Tag jest zmiennym wskaźnikiem: właściciel może w każdej chwili przypiąć go do innego obrazu. Digest (sha256:…) to skrót zawartości manifestu — ta sama wartość zawsze oznacza ten sam obraz. latest to tylko domyślna nazwa tagu, nie „najnowsza wersja”.

docker login ghcr.io
docker tag app:dev ghcr.io/org/app:1.4.2
docker push ghcr.io/org/app:1.4.2
docker image inspect --format '{{index .RepoDigests 0}}' ghcr.io/org/app:1.4.2
docker pull ghcr.io/org/app@sha256:<digest>

Większość problemów z kontenerami diagnozujesz kilkoma komendami. Kliknij objaw, a figura podpowie, od czego zacząć.

Każdy namespace izoluje jeden aspekt systemu. Docker pozwala selektywnie z nich zrezygnować, np. --network host albo --pid host. To przydatne do diagnostyki i specjalnych przypadków, ale każda taka flaga burzy jedną ścianę izolacji.

Domyślnie proces w kontenerze działa jako root, ale z okrojonym zestawem capabilities jądra i domyślnym profilem seccomp, który blokuje około 44 z ponad 300 wywołań systemowych. To rozsądna baza. Każda flaga poniżej przesuwa ją w stronę bezpieczniej albo groźniej.

BuildKit może dołączyć do obrazu atestacje: SBOM (lista pakietów w obrazie) i provenance (jak, z czego i czym obraz zbudowano). Atestacja provenance na poziomie mode=min jest dodawana do obrazów domyślnie; SBOM włączasz jawnie (--sbom=true).

docker buildx build --sbom=true --provenance=mode=max \
  -t reg/app:1.4.2 --push .
docker buildx imagetools inspect reg/app:1.4.2 --format '{{ json .SBOM }}'
docker scout cves reg/app:1.4.2

Ściąga