Tag 1: Das erste Dockerfile
Ziel: Ein eigenes Dockerfile für
notes-apischreiben, 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-apiErwartet:
.:
.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-apiErwartet (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 /tmpErwartet (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-2Achtung: 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 -7Erwartet (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/modErwartet (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 …), ersetztCMD. Deshalb lief obendustattnotes-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 -1Erwartet:
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.goFortschritt 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 idErwartet (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/DockerfileErwartet:
# 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 -cErwartet:
{"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 gleichErwartet:
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 -lErwartet:
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 -5Erwartet (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:tag01Erwartet (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 --forceErwartet (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
latestodertag01sind 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
COPYins Image. CI baut deshalb aus einem sauberen Checkout, nie aus einem Arbeitsordner (Tag 3). - Basis-Images wie
golang:1.27-alpinekommen 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 pushmacht in Produktion die Pipeline mit einem Robot-Account, nicht der Entwickler-Laptop.