Tag 3: Build-Kontext und .dockerignore
Ziel: Sehen, was beim Bauen wirklich an den Builder geht, und mit
.dockerignoreundCOPY --excludedafür sorgen, dass.env,.gitundnode_modulesdraußen bleiben. · Dauer: ca. 60 min · Voraussetzung: Tag 2
Briefing
- Der Build-Kontext ist der Ordner (oder die URL) am
Ende von
docker build. Der Client schickt ihn an BuildKit;COPY . .kann alles daraus ins Image legen. .dockerignoreim Wurzelordner des Kontexts filtert, bevor etwas übertragen wird. Was dort steht, sieht der Builder nie.- Ein Dockerfile darf eine eigene Ignore-Datei
<Dockerfile>.dockerignoredaneben haben. Sie ersetzt die allgemeine, sie ergänzt sie nicht. COPY --excludefiltert nur eine einzelne Anweisung. Die Datei bleibt im Kontext.
~/docker-lab/tag03/ .dockerignore BuildKit
┌──────────────────────┐ ┌─────────────┐ ┌──────────────────┐
│ .env .git notes-* │ ───► │ Filter │ ───► │ Kontext │
│ node_modules *.test │ │ (Client) │ │ COPY / ADD / │
└──────────────────────┘ └─────────────┘ │ --mount=type=bind│
└──────────────────┘
Drill 1: Kontextgröße messen
source ~/docker-lab/setup/env.sh
mkdir -p ~/docker-lab/tag03 && cd ~/docker-lab/tag03
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag02/notes/." .Die zweite Kopie legt den Stand vom Ende von Tag 2 darüber – auch wenn du ihn übersprungen hast. Jetzt das Dockerfile von Tag 2 bauen und auf eine Zeile achten:
docker build --progress=plain -t notes-api:tag03 notes-api 2>&1 \
| grep -E 'load build context|transferring context'Erwartet (gekürzt, kann je nach Version abweichen):
#5 [internal] load build context
#5 transferring context: 6.21kB done
Das ist alles, was aus notes-api/ an den Builder ging:
ein paar Kilobyte. Größen und Zeiten in diesem Kapitel weichen bei dir
ab, es geht um das Verhältnis.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Ballast wie im echten Projekt
Ein echtes Projekt hat ein Git-Repository, installierte Node-Pakete und Test-Binaries. Das baust du dir nach, mit Platzhaltern statt echter Pakete:
git init -q && git add -A
git -c user.name=lab -c [email protected] commit -qm "Tag 3"
mkdir -p notes-web/node_modules/riesig
dd if=/dev/zero of=notes-web/node_modules/riesig/blob bs=1048576 count=50 2>/dev/null
dd if=/dev/zero of=notes-api/notes-api.test bs=1048576 count=10 2>/dev/null
du -sh .git notes-web/node_modules notes-api/notes-api.testErwartet (gekürzt, kann je nach Version abweichen):
92K .git
50M notes-web/node_modules
10M notes-api/notes-api.test
notes-api.test steht für das, was
go test -c erzeugt. Jetzt brauchst du ein Werkzeug, das
zeigt, was vom Kontext beim Builder ankommt. Ein leeres Image, in das
alles kopiert wird, und -o type=local schreibt dessen
Dateisystem in einen Ordner:
cat > Dockerfile.kontext <<'EOF'
# syntax=docker/dockerfile:1
# Kopiert den kompletten Build-Kontext in ein leeres Image.
# Mit -o type=local,dest=<ordner> landet dessen Dateisystem in einem Ordner.
FROM scratch
COPY . /
EOF
docker build -q -f Dockerfile.kontext -o type=local,dest=/tmp/notes-kontext . >/dev/null
du -sh /tmp/notes-kontextErwartet (gekürzt, kann je nach Version abweichen):
60M /tmp/notes-kontext
Warum? Mit dem Projektordner als Kontext geht alles mit, auch 60 MB, die kein Dienst braucht. Bei jedem Build, über den Socket in die Colima-VM.
Fortschritt speichern? Kostenlos registrieren
Drill 3: Was im Image landet
Tag 0 hat es angekündigt: Mit dem Projektordner als Kontext ist die
.env drin.
ls -A /tmp/notes-kontext
cat /tmp/notes-kontext/.env
ls /tmp/notes-kontext/.git | head -3Erwartet:
.env .git Dockerfile.kontext
.env.example README.md notes-api
notes-web notes-worker
# Lokale Entwicklungswerte – Lab-Werte, niemals produktiv verwenden
NOTES_API_KEY=lab-api-key-123
COMMIT_EDITMSG
HEAD
config
Ein COPY . . in irgendeinem Dockerfile, das mit dem
Projektordner gebaut wird, legt den Key und die komplette Git-Historie
in ein Layer. Und was in einem Layer war, bleibt drin (Tag 11).
Sicherheit:
.gitist mindestens so gefährlich wie.env. Die Historie enthält oft Secrets, die im aktuellen Stand längst gelöscht sind.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Die .dockerignore im Projektordner
cat > .dockerignore <<'EOF'
# .dockerignore im Projektordner – gilt, wenn der Projektordner der Build-Kontext ist
# Secrets: nur die Vorlage darf mit
.env
.env.*
!.env.example
# Versionskontrolle und Betriebssystem
.git
**/.DS_Store
# Abhängigkeiten, Build-Ergebnisse, Caches – in jeder Tiefe
**/node_modules
**/dist
**/.venv
**/__pycache__
**/*.test
# Doku: nur die README im Wurzelordner
*.md
!README.md
EOF
rm -rf /tmp/notes-kontext
docker build -q -f Dockerfile.kontext -o type=local,dest=/tmp/notes-kontext . >/dev/null
du -sh /tmp/notes-kontext
ls -A /tmp/notes-kontext
ls notes-web /tmp/notes-kontext/notes-webErwartet (gekürzt, kann je nach Version abweichen):
120K /tmp/notes-kontext
.dockerignore Dockerfile.kontext README.md
.env.example notes-api notes-web
notes-worker
notes-web:
node_modules package-lock.json package.json public server.js
src
/tmp/notes-kontext/notes-web:
package-lock.json package.json public server.js src
Von 60 MB auf gut 100 KB, ohne .env, ohne
.git, ohne node_modules. Die Regeln
dahinter:
| Muster | trifft | trifft nicht |
|---|---|---|
.env |
./.env |
notes-api/.env |
**/node_modules |
node_modules, notes-web/node_modules |
– |
*.md |
./README.md |
notes-api/HANDBUCH.md |
!README.md |
holt ./README.md zurück |
– |
Muster gelten relativ zum Wurzelordner des Kontexts, nach den Regeln
von Gos filepath.Match plus ** für beliebig
viele Ordner. Führende und abschließende / werden
ignoriert.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Reihenfolge und Ausnahmen
Die wichtigste Regel: Die letzte passende Zeile entscheidet. Das probierst du in einem kleinen Sandkasten aus, mit dem Beispiel aus der Docker-Doku:
mkdir -p /tmp/notes-ign/node_modules /tmp/notes-ign/sub/node_modules
cd /tmp/notes-ign
touch node_modules/x sub/node_modules/y README.md NOTES.md README-secret.md
cat > .dockerignore <<'EOF'
node_modules
*.md
!README*.md
README-secret.md
EOF
rm -rf /tmp/notes-kontext
docker build -q -f ~/docker-lab/tag03/Dockerfile.kontext \
-o type=local,dest=/tmp/notes-kontext . >/dev/null
du -sh /tmp/notes-kontext
find /tmp/notes-kontext -type fErwartet (Reihenfolge kann abweichen):
4.0K /tmp/notes-kontext
/tmp/notes-kontext/sub/node_modules/y
/tmp/notes-kontext/README.md
/tmp/notes-kontext/.dockerignore
Zwei Lehren: README-secret.md fehlt, weil die Zeile
README-secret.md nach der Ausnahme !README*.md
steht und damit zuletzt passt. Und node_modules ohne
**/ trifft nur den Ordner im Wurzelverzeichnis,
sub/node_modules rutscht durch. Jetzt die Reihenfolge
drehen und **/ ergänzen:
cat > .dockerignore <<'EOF'
**/node_modules
*.md
README-secret.md
!README*.md
EOF
rm -rf /tmp/notes-kontext
docker build -q -f ~/docker-lab/tag03/Dockerfile.kontext \
-o type=local,dest=/tmp/notes-kontext . >/dev/null
du -sh /tmp/notes-kontext
find /tmp/notes-kontext -type f
cd ~/docker-lab/tag03Erwartet (Reihenfolge kann abweichen):
4.0K /tmp/notes-kontext
/tmp/notes-kontext/README.md
/tmp/notes-kontext/README-secret.md
/tmp/notes-kontext/.dockerignore
!README*.md steht jetzt zuletzt und holt
README-secret.md zurück. Wer eine Ausnahme nach unten
schreibt, öffnet sie für alles, was davor ausgeschlossen war.
Achtung:
.dockerignoreist nicht.gitignore. In.gitignoretrifftnode_modulesjede Tiefe, in.dockerignorenur den Wurzelordner. Im Zweifel**/.
Fortschritt speichern? Kostenlos registrieren
Drill 6: Die .dockerignore des Dienstes
Gebaut wird im Buch mit dem Dienstordner als Kontext. Also braucht
notes-api/ eine eigene .dockerignore. Erst
ansehen, was heute im Image unter /src liegt:
docker run --rm --entrypoint ls notes-api:tag03 -A /srcErwartet:
Dockerfile
Dockerfile.naiv
go.mod
go.sum
main.go
Das Image ist von Drill 1, vor dem Ballast. Mit dem Test-Binary von Drill 2 wären es 10 MB mehr. Jetzt die Ignore-Datei:
cat > notes-api/.dockerignore <<'EOF'
# notes-api/.dockerignore – gilt, wenn notes-api/ der Build-Kontext ist
Dockerfile*
.dockerignore
*.md
.git
.env*
**/*.test
EOF
docker build --progress=plain -t notes-api:tag03 notes-api 2>&1 \
| grep -E 'transferring context|naming to'
docker run --rm --entrypoint ls notes-api:tag03 -A /srcErwartet (gekürzt, kann je nach Version abweichen):
#5 transferring context: 4.93kB done
#9 naming to docker.io/library/notes-api:tag03 done
go.mod
go.sum
main.go
Warum klappt der Build, obwohl Dockerfile* ignoriert
wird? Dockerfile und .dockerignore gehen trotzdem an den
Builder, weil er sie zum Bauen braucht. Nur COPY,
ADD und Bind-Mounts kommen nicht mehr an sie heran. Läuft
der Dienst noch?
docker run -d --name notes-api -p 127.0.0.1:8080:8080 \
-e NOTES_API_KEY=lab-api-key-123 notes-api:tag03
sleep 3 && curl -s localhost:8080/healthz
docker ps --filter name=notes-api --format '{{.Names}} {{.Status}}'
docker rm -f notes-api >/dev/nullErwartet (gekürzt, kann je nach Version abweichen):
ok
notes-api Up 3 seconds (healthy)
Fortschritt speichern? Kostenlos registrieren
Drill 7: Eine Ignore-Datei pro Dockerfile
Manche Dockerfiles brauchen andere Regeln als der Rest. Dafür legst
du neben das Dockerfile eine Datei
<Dockerfile>.dockerignore. Hier als Whitelist: alles
raus, nur notes-api/ wieder rein.
cp Dockerfile.kontext Dockerfile.whitelist
cat > Dockerfile.whitelist.dockerignore <<'EOF'
# Whitelist: erst alles ausschließen, dann gezielt zurückholen
*
!notes-api/
# innerhalb von notes-api wieder ausschließen (letzter Treffer gewinnt)
notes-api/Dockerfile*
notes-api/**/*.test
EOF
rm -rf /tmp/notes-kontext
docker build -q -f Dockerfile.whitelist \
-o type=local,dest=/tmp/notes-kontext . >/dev/null
du -sh /tmp/notes-kontext
find /tmp/notes-kontext -type f | sortErwartet (gekürzt, kann je nach Version abweichen):
20K /tmp/notes-kontext
/tmp/notes-kontext/notes-api/.dockerignore
/tmp/notes-kontext/notes-api/go.mod
/tmp/notes-kontext/notes-api/go.sum
/tmp/notes-kontext/notes-api/main.go
Die Projekt-.dockerignore spielt für diesen Build keine
Rolle mehr, die Dockerfile-spezifische hat Vorrang. Es gibt
keine Zusammenführung: Hätte die Whitelist kein
* am Anfang, wäre die .env wieder dabei. Und
Dockerfile.whitelist.dockerignore gilt nur, weil sie im
selben Ordner liegt wie Dockerfile.whitelist.
Tipp: Whitelists (
*und dann!…) sind robuster als Blacklists. Eine neue Datei mit Secrets im Projekt landet nicht automatisch im Kontext.
Fortschritt speichern? Kostenlos registrieren
Drill 8: COPY --exclude
COPY --exclude ist seit Dockerfile-Frontend 1.19 stabil,
vorher gab es die Option nur im labs-Kanal. Mit
# syntax=docker/dockerfile:1 bekommst du die aktuelle
1.x-Version und damit --exclude.
cat > Dockerfile.exclude <<'EOF'
# syntax=docker/dockerfile:1
# COPY --exclude filtert nur diese eine Anweisung, nicht den Build-Kontext.
FROM scratch
COPY --exclude=*.md --exclude=notes-worker/uv.lock . /
EOF
rm -rf /tmp/notes-kontext
docker build -q -f Dockerfile.exclude -o type=local,dest=/tmp/notes-kontext . >/dev/null
du -sh /tmp/notes-kontext
ls /tmp/notes-kontext /tmp/notes-kontext/notes-worker
docker build --progress=plain -f Dockerfile.exclude -o type=local,dest=/tmp/x . 2>&1 \
| grep 'transferring context'
rm -rf /tmp/xErwartet (gekürzt, kann je nach Version abweichen):
112K /tmp/notes-kontext
/tmp/notes-kontext:
Dockerfile.exclude Dockerfile.whitelist.dockerignore notes-web
Dockerfile.kontext notes-api notes-worker
Dockerfile.whitelist
/tmp/notes-kontext/notes-worker:
pyproject.toml src
#4 transferring context: 71.30kB done
README.md und uv.lock fehlen im Ergebnis,
aber transferring context zeigt: Sie wurden übertragen. Ein
zweites COPY ohne --exclude oder ein
Bind-Mount käme an sie heran. Fürs Ausschließen von Secrets ist deshalb
.dockerignore zuständig; --exclude ist ein
Werkzeug für Multi-Stage-Builds, wenn eine Stage weniger kopieren soll
als eine andere (ab Tag 5).
Tipp: Der Kontext muss kein lokaler Ordner sein.
docker buildnimmt auch ein Git-Repository oder ein Tarball per URL; der Builder klont bzw. entpackt dann selbst. Auch dort gilt die.dockerignoreim Wurzelordner. Im Buch bleibt es bei lokalen Ordnern.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Was kommt mit der Projekt-.dockerignore beim Builder
an?
cd ~/docker-lab/tag03
rm -rf /tmp/notes-kontext
docker build -q -f Dockerfile.kontext -o type=local,dest=/tmp/notes-kontext . >/dev/null
ls -A /tmp/notes-kontextErwartet: keine .env, kein .git, aber
.env.example.
.dockerignore
.env.example
Dockerfile.exclude
Dockerfile.kontext
Dockerfile.whitelist
Dockerfile.whitelist.dockerignore
README.md
notes-api
notes-web
notes-worker
Im Image liegen unter /src nur die Go-Dateien:
docker run --rm --entrypoint ls notes-api:tag03 /srcErwartet:
go.mod
go.sum
main.go
Challenge
Zeig ohne Dockerfile auf der Platte, was vom Kontext beim Builder
ankommt – einmal mit der Projekt-.dockerignore, einmal
ohne. Welche Fallen (.env, .git,
node_modules, *.test) stecken jeweils
drin?
Hinweis: docker build -f - liest das
Dockerfile von stdin, der Kontext bleibt der angegebene Ordner samt
dessen .dockerignore.
Lösung
Ein Zwei-Zeilen-Dockerfile per printf auf stdin, der
Kontext ist der Projektordner:
cd ~/docker-lab/tag03
rm -rf /tmp/ctx
printf 'FROM scratch\nCOPY . /\n' \
| docker build -q -f - -o type=local,dest=/tmp/ctx . >/dev/null
find /tmp/ctx -name '.env' -o -name .git -o -name node_modules -o -name '*.test'Erwartet: keine Ausgabe, nichts davon ist im Kontext. Jetzt ohne Ignore-Datei:
mv .dockerignore .dockerignore.aus
rm -rf /tmp/ctx
printf 'FROM scratch\nCOPY . /\n' \
| docker build -q -f - -o type=local,dest=/tmp/ctx . >/dev/null
find /tmp/ctx -name '.env' -o -name .git -o -name node_modules -o -name '*.test'
mv .dockerignore.aus .dockerignoreErwartet:
/tmp/ctx/notes-web/node_modules
/tmp/ctx/notes-api/notes-api.test
/tmp/ctx/.git
/tmp/ctx/.env
Alle vier Fallen wären ohne .dockerignore im Kontext.
Diesen Build ohne Dockerfile kannst du in CI vor jeden echten Build
stellen. Zum Schluss aufräumen:
rm -rf /tmp/notes-kontext /tmp/notes-ign /tmp/ctx
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 --forceFortschritt speichern? Kostenlos registrieren
Enterprise-Notiz
.dockerignoregehört ins Repository und in jedes Code-Review. Eine Zeile zu wenig lässt Secrets in den Kontext, eine zu viel bricht den Build mitCOPY failed(Tag 15).- In Monorepos lieber pro Dienst bauen oder Whitelist-Ignore-Dateien pro Dockerfile nutzen, statt den Wurzelordner mit Gigabytes an Abhängigkeiten zu übertragen.
- CI-Runner checken das Repository mit
.gitaus. Ohne.gitin.dockerignorelandet die Historie im Image, sobald irgendwoCOPY . .steht. - Remote-Kontexte (Git-URL) sind praktisch, aber prüfe Herkunft und Ref: Ein Branch-Name ist beweglich, ein Commit-SHA nicht.
- Secret-Scanner wie
trivy image --scanners secret(Tag 11) finden Leaks im Image, der Filter in.dockerignoreverhindert sie. Du brauchst beides.