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-apiReproduzierbar 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.dockerignoreneben 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 . /ctxundRUN find /ctx -type fin 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 .gitignoreLaufzeit-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:tag14Ports 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 dfFehlerbilder
| 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) |