Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 3: Build-Kontext und .dockerignore

Ziel: Sehen, was beim Bauen wirklich an den Builder geht, und mit .dockerignore und COPY --exclude dafür sorgen, dass .env, .git und node_modules drauß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.
  • .dockerignore im Wurzelordner des Kontexts filtert, bevor etwas übertragen wird. Was dort steht, sieht der Builder nie.
  • Ein Dockerfile darf eine eigene Ignore-Datei <Dockerfile>.dockerignore daneben haben. Sie ersetzt die allgemeine, sie ergänzt sie nicht.
  • COPY --exclude filtert 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.test

Erwartet (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-kontext

Erwartet (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 -3

Erwartet:

.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: .git ist 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-web

Erwartet (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 f

Erwartet (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/tag03

Erwartet (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: .dockerignore ist nicht .gitignore. In .gitignore trifft node_modules jede Tiefe, in .dockerignore nur 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 /src

Erwartet:

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 /src

Erwartet (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/null

Erwartet (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 | sort

Erwartet (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/x

Erwartet (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 build nimmt auch ein Git-Repository oder ein Tarball per URL; der Builder klont bzw. entpackt dann selbst. Auch dort gilt die .dockerignore im 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-kontext

Erwartet: 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 /src

Erwartet:

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 .dockerignore

Erwartet:

/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 --force

Fortschritt speichern? Kostenlos registrieren

Enterprise-Notiz

  • .dockerignore gehört ins Repository und in jedes Code-Review. Eine Zeile zu wenig lässt Secrets in den Kontext, eine zu viel bricht den Build mit COPY 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 .git aus. Ohne .git in .dockerignore landet die Historie im Image, sobald irgendwo COPY . . 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 .dockerignore verhindert sie. Du brauchst beides.