Zum Inhalt springen
Trainingslager IT-Trainingslager

Anhang A: Spickzettel

Alles Wichtige aus Tag 1–15 auf wenigen Seiten. Die Zahl in Klammern ist der Tag, an dem du es geübt hast. Im Zweifel gilt die Dockerfile-Referenz unter docs.docker.com/reference/dockerfile/ und docker build --check.

Das Muster-Dockerfile

Der Stand, auf den das Buch hinarbeitet (Tag 5, 7, 9, 10). Für eigene Go-Dienste genügt es meist, Pfade und Namen zu tauschen.

# syntax=docker/dockerfile:1
# check=error=true
ARG GO_VERSION=1.27
# in Produktion: @sha256:… pinnen, siehe Tag 8
FROM --platform=$BUILDPLATFORM golang:${GO_VERSION}-alpine AS base
WORKDIR /src
COPY go.mod go.sum ./
RUN --mount=type=cache,target=/go/pkg/mod go mod download
COPY . .

FROM base AS test
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    go vet ./... && go test ./...

FROM base AS build
ARG TARGETOS TARGETARCH VERSION=dev
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 GOOS=$TARGETOS GOARCH=$TARGETARCH \
    go build -trimpath -ldflags="-s -w -X main.version=${VERSION}" -o /out/notes-api .

FROM scratch AS final
ARG VERSION=dev REVISION=unknown CREATED=unknown
LABEL org.opencontainers.image.title="notes-api" \
      org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.revision="${REVISION}" \
      org.opencontainers.image.created="${CREATED}"
COPY --link --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
COPY --link --from=build /out/notes-api /notes-api
USER 65532:65532
EXPOSE 8080
HEALTHCHECK --interval=10s --timeout=2s --start-period=5s --start-interval=1s \
    CMD ["/notes-api", "healthcheck"]
STOPSIGNAL SIGTERM
ENTRYPOINT ["/notes-api"]

Anweisungen

Anweisung Merksatz Tag
FROM img AS name Basis plus Stage-Name; --platform=$BUILDPLATFORM für Cross-Compile 1, 5, 7
ARG nur Build-Zeit; vor FROM global, im Stage neu deklarieren; nie Secrets 2, 11
ENV Build- und Laufzeit, steht im Image-Config; nie Secrets 2, 11
WORKDIR immer absolut, legt den Ordner an 1
COPY Dateien aus Kontext, Stage oder Image; Abhängigkeiten zuerst 1, 4, 5
ADD nur für URLs/Git mit --checksum, sonst COPY 1
RUN neuer Layer; Mounts für Cache und Secrets 1, 4, 13
USER numerisch 65532:65532, vor ENTRYPOINT 2, 9
EXPOSE Dokumentation, öffnet nichts 2
LABEL OCI-Annotationen org.opencontainers.image.* 2, 10
HEALTHCHECK Exec-Form, eigenes Binary statt curl; nur der letzte zählt 2, 15
STOPSIGNAL Standard SIGTERM; docker stop wartet 10 s, dann SIGKILL 2
ENTRYPOINT Exec-Form, damit der Prozess PID 1 ist und Signale bekommt 2
CMD Standard-Argumente für ENTRYPOINT 2
SHELL ändert die Shell der Shell-Form, z. B. für pipefail 2

Kopf jeder Datei: # syntax=docker/dockerfile:1, danach optional # check=error=true oder # check=skip=<Regel>;error=true (Tag 9).

ENTRYPOINT und CMD

ENTRYPOINT CMD Gestartet wird
– ["notes-api"] notes-api
["notes-api"] – notes-api
["notes-api"] ["--help"] notes-api --help
notes-api (Shell-Form) beliebig /bin/sh -c notes-api, CMD wird ignoriert

Shell-Form heißt: PID 1 ist /bin/sh, SIGTERM erreicht die Anwendung nicht zuverlässig. In Startskripten deshalb exec programm "$@" (Tag 2, Tag 15).

COPY und ADD

Option Wirkung Ab Dockerfile Tag
--from=<stage> aus einer Stage oder einem fremden Image kopieren – 5, 7
--chown=65532:65532 Besitzer setzen, ohne extra RUN chown-Layer – 9
--chmod=0755 Rechte setzen; symbolisch (u+x) erst ab 1.14 1.2 9
--link Layer unabhängig vom Vorgänger, besserer Cache-Reuse 1.4 7
--exclude=<muster> Muster beim Kopieren auslassen 1.19 3
--parents Verzeichnisstruktur der Quelle erhalten 1.20 3
ADD --checksum=sha256:… Download nur mit passender Prüfsumme 1.6 8

Build-Flags

Flag Wirkung Tag
-t name:tag, -f datei Name vergeben, anderes Dockerfile (-f - von stdin) 1, 15
--target test nur bis zu dieser Stage bauen 5, 7
--build-arg K=V ARG setzen; landet in History und Provenance 2, 11
--progress=plain volle Ausgabe inkl. CACHED und RUN-Ausgaben 4
--no-cache, --pull Cache ignorieren, Base-Image neu ziehen 4
--check nur Build Checks, kein Build; Exit ≠ 0 bei Funden 9
-q nur Image-ID ausgeben 1
--builder docker-lab eigenen BuildKit-Builder nutzen 4, 7, 10
--platform linux/amd64,linux/arm64 Multi-Plattform (nur mit --push o. ä.) 7
--push, --load Ergebnis in Registry bzw. lokalen Image-Store 7, 10
--cache-to, --cache-from Cache exportieren/importieren, z. B. type=registry 4
--secret id=…,src=… Datei als Build-Secret; ,env=VAR aus Umgebung 13
--ssh default SSH-Agent für RUN --mount=type=ssh 13
--sbom=true SBOM-Attestation anhängen 10
--provenance=mode=max ausführliche Provenance; enthält Build-Arg-Werte 10
--label k=v Label beim Build setzen 10

Cache in der Registry (Tag 4):

docker buildx build --builder docker-lab \
  --cache-to type=registry,ref=localhost:5001/notes-api:buildcache,mode=max \
  --cache-from type=registry,ref=localhost:5001/notes-api:buildcache \
  -t localhost:5001/notes-api:dev --push notes-api

Reproduzierbar bauen (Tag 10): --build-arg SOURCE_DATE_EPOCH=$(git log -1 --pretty=%ct).

RUN-Mounts

Typ Wichtige Optionen Einsatz Tag
cache target, id, sharing (shared, private, locked) Go-, uv-, npm-Caches 4
bind source, target, from, standardmäßig read-only Dateien nur für einen Schritt 4
secret id, target, env, required, mode (0400) Tokens beim Build 13
ssh id (default), required private Git-Repos 13
tmpfs target, size Scratch-Platz im Speicher –
# syntax=docker/dockerfile:1
FROM golang:1.27-alpine
WORKDIR /src
# Go: Module und Build-Cache
RUN --mount=type=cache,target=/go/pkg/mod \
    --mount=type=cache,target=/root/.cache/go-build \
    --mount=type=bind,target=. \
    go build -o /out/app .
# Secret als Datei unter /run/secrets/<id> (Standardpfad)
RUN --mount=type=secret,id=artifact_token,required=true \
    test -s /run/secrets/artifact_token
# Secret als Umgebungsvariable nur für diesen Schritt (ab Dockerfile 1.10)
RUN --mount=type=secret,id=artifact_token,env=ARTIFACT_TOKEN \
    test -n "$ARTIFACT_TOKEN"

Weitere Cache-Ziele: uv /root/.cache/uv, npm /root/.npm (Tag 6). Secret-Mounts gehen nicht in den Cache-Schlüssel ein: Ein neuer Token-Wert baut den Schritt nicht neu (Tag 13).

Build Checks

docker build --check notes-api
docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=error=true" notes-api
docker build --check --build-arg "BUILDKIT_DOCKERFILE_CHECK=experimental=all" notes-api
Regel Findet Tag
SecretsUsedInArgOrEnv Namen wie *_KEY, *_TOKEN in ARG/ENV 11
JSONArgsRecommended Shell-Form bei CMD/ENTRYPOINT 2
FromAsCasing FROM … as … gemischt mit Großschreibung 9
UndefinedVar, UndefinedArgInFrom Variablen ohne Deklaration 2, 7
CopyIgnoredFile COPY einer Datei, die .dockerignore ausschließt 3, 15
WorkdirRelativePath relatives WORKDIR ohne absolutes davor 1
RedundantTargetPlatform --platform=$TARGETPLATFORM ist überflüssig 7
LegacyKeyValueFormat ENV K V statt ENV K=V 2

Daneben hadolint notes-api/Dockerfile mit Konfiguration .hadolint.yaml im Projektordner (Tag 9).

Werkzeug prüft Tag
hadolint Dockerfile als Text, RUN mit ShellCheck 9
Build Checks Dockerfile beim Build (BuildKit) 9
dockle fertiges Image (CIS-Benchmark) 9
trivy Dockerfile (config), Ordner (fs), Image, SBOM 10, 11
ShellCheck Shell-Skripte 10

.dockerignore

# Kommentare nur am Zeilenanfang, nie hinter einem Muster
# Dockerfile bleibt für BuildKit lesbar, landet aber nicht im COPY
Dockerfile*
.dockerignore
.git
# alle .env-Varianten außer der Vorlage
.env*
!.env.example
*.md
# ** passt auf beliebig viele Ordnerebenen
**/node_modules
**/__pycache__
  • Muster gelten relativ zur Wurzel des Kontexts, die letzte passende Zeile gewinnt.
  • Dockerfile.distroless.dockerignore neben dem Dockerfile hat Vorrang vor der allgemeinen .dockerignore (Tag 3).
  • Allowlist (* plus !…) ist streng, vergisst aber leicht Dateien (Tag 15, Runde 9).
  • Was im Kontext landet, zeigt ein Kontext-Spion: COPY . /ctx und RUN find /ctx -type f in einem Wegwerf-Dockerfile.

Das Secrets-Dreieck

Datei Zweck Ins Git? Tag
.env lokale Werte, auch Lab-Secrets nein 12
.env.example Vorlage mit allen Namen, ohne Werte ja 12
.gitignore hält .env, secrets/ aus dem Repository ja 12
.dockerignore hält dieselben Muster aus dem Build-Kontext ja 3, 12
Weg ins Image oder in den Container Sicher? Nachweis Tag
ARG / --build-arg ✘ docker history --no-trunc, Provenance 11
ENV ✘ docker image inspect, docker inspect 11
COPY .env / RUN … && rm ✘ Layer bleibt, docker save 11
RUN --mount=type=secret ✔ nicht in History, nicht im Layer 13
-e/env_file: zur Laufzeit bedingt sichtbar in docker inspect 12, 14
Datei unter /run/secrets/ + *_FILE ✔ nur Pfad in docker inspect 14
Mechanismus Wirkt auf Tag
.env neben compose.yaml Interpolation von ${VAR} in der Compose-Datei 12
env_file: Umgebung im Container 12
docker run --env-file Umgebung im Container 12
docker compose config zeigt aufgelöste Werte – Achtung Leak 12

Merksatz: Was einmal in einem Layer war, bleibt drin. Ein geleakter Key wird rotiert, nicht nur gelöscht (Tag 11, Tag 15).

Compose-Secrets

services:
  notes-api:
    build:
      context: notes-api
      secrets:
        - artifact_token          # Build-Secret (Tag 13)
    environment:
      NOTES_API_KEY_FILE: /run/secrets/notes_api_key
    secrets:
      - notes_api_key             # Laufzeit-Secret (Tag 14)
    ports:
      - "127.0.0.1:8080:8080"
secrets:
  artifact_token:
    environment: ARTIFACT_TOKEN   # Wert aus der Shell-Umgebung
  notes_api_key:
    file: ./secrets/notes_api_key.txt   # Datei steht in .gitignore

Laufzeit-Secrets liegen im Container unter /run/secrets/<name>. Rotieren ohne Rebuild: Datei ändern, docker compose up -d --force-recreate notes-api (Tag 14).

Laufzeit-Härtung

docker run -d --name notes-api \
  --read-only --tmpfs /tmp \
  --cap-drop ALL --security-opt no-new-privileges \
  --user 65532:65532 \
  -e NOTES_API_KEY_FILE=/run/secrets/notes_api_key \
  -v "$PWD/secrets/notes_api_key.txt:/run/secrets/notes_api_key:ro" \
  -p 127.0.0.1:8080:8080 notes-api:tag14

Ports nur auf 127.0.0.1, --init nur, wenn das Image kein eigenes Signal-Handling hat (Tag 2, Tag 9).

Inspektion

# Layer und Herkunft (Tag 1, 11)
docker history --no-trunc --format '{{.CreatedBy}}' notes-api:tag14
docker image inspect --format '{{json .Config}}' notes-api:tag14 | jq .
docker image inspect --format '{{.Config.User}} {{.Os}}/{{.Architecture}}' \
  notes-api:tag14
docker image ls --digests localhost:5001/notes-api

# laufender Container (Tag 2, 9, 14)
docker inspect --format '{{.State.Health.Status}}' notes-api
docker inspect --format '{{json .State.Health.Log}}' notes-api | jq -r '.[-1].Output'
docker inspect --format '{{json .Config.Env}}' notes-api
docker top notes-api
docker logs notes-api

# Registry, Plattformen, Attestations (Tag 7, 8, 10)
docker buildx imagetools inspect localhost:5001/notes-api:tag10
docker buildx imagetools inspect localhost:5001/notes-api:tag10 \
  --format '{{json .SBOM}}'
docker buildx imagetools inspect localhost:5001/notes-api:tag10 \
  --format '{{json .Provenance}}'

# Scanner und Linter (Tag 9, 10, 11)
hadolint notes-api/Dockerfile
trivy config --severity HIGH,CRITICAL --exit-code 1 notes-api/Dockerfile
trivy image --severity HIGH,CRITICAL --exit-code 1 notes-api:tag14
trivy image --scanners secret notes-api:tag14
trivy fs --scanners secret .
dockle --exit-code 1 --exit-level warn notes-api:tag14   # Ausnahmen: .dockleignore
shellcheck -S warning ~/docker-lab/code/tag*/*.sh       # Direktiven: # shellcheck …

# Git und Kontext (Tag 3, 12)
git check-ignore -v .env
git status --ignored --short
docker system df

Fehlerbilder

Symptom Ursache Fix
Image über 1 GB Compiler und Caches im Final-Image Multi-Stage, scratch/distroless (5)
jeder Build lädt alles neu COPY . . vor den Abhängigkeiten Lockfiles zuerst, Cache-Mount (4)
Key in History/Config ARG/ENV mit Secret Secret-Mount, rotieren (11, 13)
.env im Image fehlende .dockerignore, COPY . . .dockerignore, gezielt kopieren (3)
läuft als root kein USER USER 65532:65532 (9)
docker stop dauert 10 s Shell als PID 1 Exec-Form, exec im Skript (2)
exec format error falsche Architektur im Binary TARGETOS/TARGETARCH (7)
x509: … unknown authority CA-Bündel fehlt in scratch ca-certificates.crt kopieren (5)
"/go.sum": not found .dockerignore zu gierig Ausnahme !go.sum, --check (3)
unhealthy ohne Grund Healthcheck braucht Shell/curl Exec-Form mit eigenem Binary (2)