Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 1: Das erste Dockerfile

Ziel: Ein eigenes Dockerfile für notes-api schreiben, Image und Container auseinanderhalten, Layer lesen und das Image per Tag und Digest in die lokale Registry bringen. · Dauer: ca. 60 min · Voraussetzung: Tag 0

Briefing

  • Ein Dockerfile ist ein Bauplan. Jede Anweisung (FROM, WORKDIR, COPY, RUN, CMD) erzeugt einen Schritt; die dateiverändernden Schritte werden zu Layern.
  • Ein Image ist der Stapel aus Layern plus Konfiguration, unveränderlich. Ein Container ist ein laufender Prozess auf diesem Image mit einer eigenen, beschreibbaren Schicht obendrauf.
  • Ein Tag (notes-api:tag01) ist ein verschiebbarer Name, ein Digest (sha256:…) die feste Prüfsumme genau eines Manifests.
 Dockerfile            Image notes-api:tag01           Container notes-api
 FROM golang:…  ──►   ┌─────────────────────────┐    ┌──────────────────────┐
 WORKDIR /src   ──►   │ RUN go build   (Layer)  │    │ beschreibbare Schicht│
 COPY . .       ──►   │ COPY . .       (Layer)  │ ─► ├──────────────────────┤
 RUN go build   ──►   │ WORKDIR /src   (Layer)  │    │ Image (nur lesend)   │
 CMD [...]      ──►   │ golang:1.27-alpine …    │    └──────────────────────┘
                      │ Config: Cmd, Env, …     │
                      └─────────────────────────┘

Drill 1: Arbeitsplatz für Tag 1

source ~/docker-lab/setup/env.sh
mkdir -p ~/docker-lab/tag01 && cd ~/docker-lab/tag01
cp -R "$LAB/code/notes/." .
ls -A . notes-api

Erwartet:

.:
.env            .env.example    notes-api       notes-web       notes-worker
README.md

notes-api:
Dockerfile.naiv go.mod          go.sum          main.go

Ab heute arbeitet jeder Tag in seinem eigenen Ordner ~/docker-lab/tagNN. Das Original unter ~/docker-lab/notes bleibt unberührt.

Fortschritt speichern? Kostenlos registrieren

Drill 2: Fünf Zeilen Dockerfile

Du schreibst das Dockerfile neu, ohne die Fehler des naiven: kleineres Base-Image golang:1.27-alpine, kein Key im Image, CMD in Exec-Form.

cat > notes-api/Dockerfile <<'EOF'
# syntax=docker/dockerfile:1
FROM golang:1.27-alpine
WORKDIR /src
COPY . .
RUN go build -o /usr/local/bin/notes-api .
CMD ["notes-api"]
EOF
hadolint notes-api/Dockerfile && echo "hadolint: ok"

Erwartet:

hadolint: ok
Zeile Wirkung
# syntax=docker/dockerfile:1 BuildKit holt das aktuelle Dockerfile-Frontend der Version 1
FROM golang:1.27-alpine Base-Image: Go-Toolchain auf Alpine Linux
WORKDIR /src legt /src an und macht es zum aktuellen Verzeichnis
COPY . . kopiert den Build-Kontext nach /src
RUN go build … führt einen Befehl im Image aus, das Ergebnis wird ein Layer
CMD ["notes-api"] Standardbefehl beim Start, speichert nur Konfiguration

Die Datei liegt auch unter ~/docker-lab/code/tag01/notes/notes-api/Dockerfile.

Fortschritt speichern? Kostenlos registrieren

Drill 3: Bauen

Der letzte Parameter ist der Build-Kontext: der Ordner, den docker build an BuildKit schickt. Nur was darin liegt, kann COPY sehen.

docker build -t notes-api:tag01 notes-api

Erwartet (gekürzt, kann je nach Version abweichen):

[+] Building 21.4s (11/11) FINISHED                              docker:colima
 => [internal] load build definition from Dockerfile                      0.0s
 => resolve image config for docker-image://docker.io/docker/dockerfile:1  1.0s
 => [internal] load metadata for docker.io/library/golang:1.27-alpine     1.0s
 => [1/4] FROM docker.io/library/golang:1.27-alpine@sha256:…              9.8s
 => [internal] load build context                                         0.0s
 => [2/4] WORKDIR /src                                                    0.2s
 => [3/4] COPY . .                                                        0.0s
 => [4/4] RUN go build -o /usr/local/bin/notes-api .                      8.9s
 => exporting to image                                                    1.1s
 => => naming to docker.io/library/notes-api:tag01                        0.0s

Keine Warnung mehr: Exec-Form beim CMD und kein ENV mit Key. Baust du gleich noch einmal, steht bei jedem Schritt CACHED und der Build dauert eine Sekunde (Tag 4).

docker image ls --format '{{.Repository}}:{{.Tag}}  {{.Size}}' \
  | grep -E '^(notes-api|golang):'

Erwartet (kann je nach Version abweichen):

notes-api:tag01  340MB
golang:1.27-alpine  263MB

Image-Größen, Digests und Build-Zeiten in diesem Buch weichen bei dir ab. Vergleiche das Verhältnis: ein Drittel vom naiven Image, aber immer noch weit mehr als das Binary.

Fortschritt speichern? Kostenlos registrieren

Drill 4: Image gegen Container

Zuerst ohne Key starten:

docker run --rm notes-api:tag01; echo "Exit-Code: $?"

Erwartet (gekürzt, kann je nach Version abweichen):

time=… level=ERROR msg="start abgebrochen" err="NOTES_API_KEY oder …"
Exit-Code: 1

Gut so: Der Key gehört nicht ins Image, sondern kommt beim Start dazu. Jetzt zwei Container aus demselben Image:

docker run -d --name notes-api -p 127.0.0.1:8080:8080 \
  -e NOTES_API_KEY=lab-api-key-123 notes-api:tag01
docker run -d --name notes-api-2 -p 127.0.0.1:8081:8080 \
  -e NOTES_API_KEY=lab-api-key-123 notes-api:tag01
curl -s -X POST localhost:8080/notes -H 'X-API-Key: lab-api-key-123' \
  -d '{"text":"nur in Container 1"}'
curl -s localhost:8080/notes; curl -s localhost:8081/notes
docker ps --filter name=^notes-api --format '{{.Names}}\t{{.Image}}\t{{.Ports}}'

Erwartet (gekürzt, IDs weichen ab):

{"id":"3a7e…","text":"nur in Container 1"}
[{"id":"3a7e…","text":"nur in Container 1"}]
[]
notes-api-2   notes-api:tag01   127.0.0.1:8081->8080/tcp
notes-api     notes-api:tag01   127.0.0.1:8080->8080/tcp

Ein Image, zwei unabhängige Prozesse. Jeder Container hat außerdem eine eigene beschreibbare Schicht:

docker exec notes-api sh -c 'echo spur > /tmp/spur.txt'
docker diff notes-api
docker exec notes-api-2 ls /tmp

Erwartet (kann je nach Version abweichen):

C /tmp
A /tmp/spur.txt

A heißt hinzugefügt, C geändert. notes-api-2 sieht die Datei nicht, das Image bleibt unverändert. Mit docker rm -f ist die Spur weg:

docker rm -f notes-api notes-api-2

Achtung: Was ein Container zur Laufzeit schreibt, verschwindet mit ihm. Daten, die bleiben sollen, gehören in ein Volume, nicht in die Container-Schicht.

Fortschritt speichern? Kostenlos registrieren

Drill 5: Layer lesen

docker history --format 'table {{.CreatedBy}}\t{{.Size}}' notes-api:tag01 | head -7

Erwartet (gekürzt, kann je nach Version abweichen):

CREATED BY                                      SIZE
CMD ["notes-api"]                               0B
RUN /bin/sh -c go build -o /usr/local/bin/no…   77.1MB
COPY . . # buildkit                             9.63kB
WORKDIR /src                                    0B
WORKDIR /go                                     0B
RUN /bin/sh -c mkdir -p "$GOPATH/src" "$GOPA…   0B

Oben stehen deine vier Anweisungen, darunter die des Base-Images. CMD hat 0 Byte: Es ist nur Konfiguration. Die steht in docker image inspect:

docker image inspect notes-api:tag01 \
  | jq '.[0] | {Arch: .Architecture, Cmd: .Config.Cmd,
                Workdir: .Config.WorkingDir, Layers: (.RootFS.Layers | length)}'

Erwartet (gekürzt, kann je nach Version abweichen):

{
  "Arch": "arm64",
  "Cmd": [
    "notes-api"
  ],
  "Workdir": "/src",
  "Layers": 8
}

Warum ist der RUN-Layer 77 MB groß, wenn das Programm klein ist? Schau nach:

docker run --rm notes-api:tag01 \
  du -sh /usr/local/bin/notes-api /root/.cache/go-build /go/pkg/mod

Erwartet (kann je nach Version abweichen):

8.9M    /usr/local/bin/notes-api
67.0M   /root/.cache/go-build
1.4M    /go/pkg/mod

Der Go-Build-Cache und die Module liegen mit im Layer. Was ein RUN schreibt, bleibt im Image, auch wenn es niemand mehr braucht. Tag 4 lagert den Cache in einen Cache-Mount aus, Tag 5 wirft die ganze Toolchain per Multi-Stage weg.

Tipp: Was nach dem Image-Namen steht (du -sh …), ersetzt CMD. Deshalb lief oben du statt notes-api. Wie man das gezielt steuert, zeigt Tag 2.

Fortschritt speichern? Kostenlos registrieren

Drill 6: Tag und Digest

Ein Tag ist nur ein Name. Für die Registry bekommt das Image einen zweiten:

docker tag notes-api:tag01 localhost:5001/notes-api:tag01
docker push localhost:5001/notes-api:tag01
OLD=$(docker image inspect --format '{{index .RepoDigests 0}}' \
  localhost:5001/notes-api:tag01)
echo "$OLD"

Erwartet (gekürzt, Digests weichen ab):

The push refers to repository [localhost:5001/notes-api]
…: Pushed
tag01: digest: sha256:4e0c… size: 1609
localhost:5001/notes-api@sha256:4e0c…

RepoDigests gibt es erst nach dem Push oder Pull: Der Digest ist die Prüfsumme des Manifests, das in der Registry liegt. Jetzt änderst du den Code und schiebst denselben Tag noch einmal:

echo '// Tag 1: Tag verschoben' >> notes-api/main.go
docker build -q -t localhost:5001/notes-api:tag01 notes-api
docker push -q localhost:5001/notes-api:tag01
curl -sI localhost:5001/v2/notes-api/manifests/tag01 | grep Digest
echo "alt: ${OLD#*@}"

Erwartet (gekürzt, Digests weichen ab):

sha256:b71d…
localhost:5001/notes-api:tag01
Docker-Content-Digest: sha256:2f6537a9d0c7…
alt: sha256:4e0c…

Der Tag tag01 zeigt jetzt auf einen anderen Digest. Wer notes-api:tag01 zieht, bekommt ab sofort den neuen Stand, ohne es zu merken. Der alte Stand ist aber nicht verloren, er ist über seinen Digest weiter abrufbar:

curl -sI "localhost:5001/v2/notes-api/manifests/${OLD#*@}" | head -1

Erwartet:

HTTP/1.1 200 OK

localhost:5001/notes-api@sha256:… liefert immer genau dasselbe Image. Darum pinnen Tag 8 und Tag 10 über den Digest. Die Codeänderung machst du rückgängig:

cp "$LAB/code/notes/notes-api/main.go" notes-api/main.go

Fortschritt speichern? Kostenlos registrieren

Drill 7: Was noch fehlt

Gegenüber dem naiven Image von Tag 0 (1.07GB) ist notes-api:tag01 auf ein Drittel geschrumpft, und der Key steckt nicht mehr in der Konfiguration:

docker image inspect --format '{{json .Config.Env}}' notes-api:tag01 \
  | grep -c NOTES_API_KEY
docker image inspect --format 'User: "{{.Config.User}}"' notes-api:tag01
docker run --rm notes-api:tag01 id

Erwartet (kann je nach Version abweichen):

0
User: ""
uid=0(root) gid=0(root) groups=0(root),1(bin),2(daemon),3(sys),4(adm),6(disk),…

Kein USER gesetzt, also läuft der Prozess als root. Außerdem fehlen ein Healthcheck, eine Versionsangabe und ein sauberer Umgang mit Signalen; und die Go-Toolchain liegt weiter im Image. Die ersten Punkte erledigt Tag 2, die Toolchain verschwindet an Tag 5. Der Key wird zur Laufzeit übergeben, das reicht für heute. Warum -e nicht das Ende ist, klärt Tag 14.

Fortschritt speichern? Kostenlos registrieren

Kontrollpunkt

Das Dockerfile von heute:

cd ~/docker-lab/tag01
cat notes-api/Dockerfile

Erwartet:

# syntax=docker/dockerfile:1
FROM golang:1.27-alpine
WORKDIR /src
COPY . .
RUN go build -o /usr/local/bin/notes-api .
CMD ["notes-api"]

hadolint hat nichts zu meckern:

hadolint notes-api/Dockerfile; echo "Exit: $?"

Erwartet:

Exit: 0

tag01 liegt in der Registry:

curl -s localhost:5001/v2/notes-api/tags/list | jq -c

Erwartet:

{"name":"notes-api","tags":["naiv","tag01"]}

main.go ist wieder im Originalzustand (Drill 6):

diff notes-api/main.go "$LAB/code/notes/notes-api/main.go" && echo gleich

Erwartet:

gleich

Challenge

Wie viel vom Image notes-api:tag01 gehört eigentlich dir und wie viel dem Base-Image? Finde deine eigenen Layer mit Größe und Befehl und vergleiche die Größe beider Images.

Hinweis: Die History des Base-Images ist das untere Ende der History deines Images; die Differenz der Zeilenzahlen sind deine Layer.

Lösung

Das Base-Image hat BuildKit nur intern geladen; docker pull holt es als Image mit Tag dazu. Wie viele Layer haben beide Images?

docker pull -q golang:1.27-alpine
docker history -q notes-api:tag01 | wc -l
docker history -q golang:1.27-alpine | wc -l

Erwartet:

docker.io/library/golang:1.27-alpine
14
10

Die Differenz sind deine Layer, sie stehen oben in der History:

docker history notes-api:tag01 | head -5

Erwartet (gekürzt, kann je nach Version abweichen):

IMAGE          CREATED         CREATED BY                                      SIZE
b865b4fa6492   3 minutes ago   CMD ["notes-api"]                               0B
<missing>      3 minutes ago   RUN /bin/sh -c go build -o /usr/local/bin/no…   112MB
<missing>      4 minutes ago   COPY . . # buildkit                             32.8kB
<missing>      27 hours ago    WORKDIR /src                                    8.19kB

Und die Größe beider Images:

docker image ls golang:1.27-alpine
docker image ls notes-api:tag01

Erwartet (gekürzt, kann je nach Version abweichen):

IMAGE                ID             DISK USAGE   CONTENT SIZE   EXTRA
golang:1.27-alpine   d200d2dd76b0        382MB         75.5MB
IMAGE             ID             DISK USAGE   CONTENT SIZE   EXTRA
notes-api:tag01   b865b4fa6492        524MB          106MB

14 minus 10: vier Layer gehören dir, rund 140 MB von 524 MB. Rund drei Viertel des Images sind Go-Toolchain und Alpine, die zur Laufzeit niemand braucht. Und von deinem Viertel ist der größte Teil Build-Cache. Zum Schluss aufräumen:

docker ps -a --filter name=^notes- --format '{{.Names}}' | xargs -r docker rm -f
docker image ls --format '{{.Repository}}:{{.Tag}}' \
  | grep -E '^(notes-|localhost:5001/)' | xargs -r docker rmi
docker buildx prune --builder docker-lab --all --force

Erwartet (gekürzt, Namen, IDs und Größen weichen ab):

Untagged: notes-api:tag01
Deleted: sha256:…
…
Total:  …

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • Image-Tags wie latest oder tag01 sind in Produktion nur ein Hinweis. Deployments referenzieren den Digest, die meisten Registries erlauben zusätzlich „immutable tags”.
  • Der Build-Kontext ist eine Sicherheitsgrenze: Alles darin kann per COPY ins Image. CI baut deshalb aus einem sauberen Checkout, nie aus einem Arbeitsordner (Tag 3).
  • Basis-Images wie golang:1.27-alpine kommen in Firmen aus einem geprüften Spiegel und werden zentral aktualisiert (Tag 8).
  • Laufzeit-Konfiguration und Secrets kommen aus der Plattform (Kubernetes-Secret, Vault/OpenBao, CI-Variablen), nie aus dem Image (Tag 14).
  • docker push macht in Produktion die Pipeline mit einem Robot-Account, nicht der Entwickler-Laptop.