Tag 12: .env, .gitignore und .dockerignore – das Dreieck
Ziel: Die
.envaus Git und Build-Kontext heraushalten, einen schon committeten Key sauber entfernen und verstehen, wie Compose die.envliest. · Dauer: ca. 75 min · Voraussetzung: Tag 11
Briefing
.envhält lokale Werte, auch Secrets. Sie bleibt auf deinem Rechner..env.examplenennt alle Variablen ohne Werte und kommt ins Repository..gitignorehält die.envaus Git,.dockerignoreaus dem Build-Kontext. Gleiche Absicht, unterschiedliche Mustersyntax.- Compose liest die
.envvon selbst, aber nur für${…}incompose.yaml. In den Container kommt sie erst überenv_file:.
.env (lokal, nie committen)
┌────────────┼──────────────┐
.gitignore Compose: .dockerignore
nicht ins Repo ${…} und nicht in den Kontext
env_file:
└────────────┼──────────────┘
.env.example (Namen ohne Werte, ins Repo)
Drill 1: Ein Repository für notes
source ~/docker-lab/setup/env.sh
mkdir -p ~/docker-lab/tag12 && cd ~/docker-lab/tag12
cp -R "$LAB/code/notes/." . && cp -R "$LAB/code/tag11/notes/." .Die zweite Kopie legt den Stand vom Ende von Tag 11 darüber – auch
wenn du ihn übersprungen hast. Bisher war notes kein
Git-Repository. Das ändert sich jetzt:
git init -b main
git status --shortErwartet:
Initialized empty Git repository in /Users/du/docker-lab/tag12/.git/
?? .dockerignore
?? .env
?? .env.example
?? .hadolint.yaml
?? README.md
?? notes-api/
?? notes-web/
?? notes-worker/
Für Git ist die .env eine Datei wie jede andere. Es gibt
noch keine .gitignore.
Sicherheit: Das Repository bleibt lokal. Kein
git remote add, kein Push – auch nicht in ein privates Repository.
Fortschritt speichern? Kostenlos registrieren
Drill 2: Der Klassiker – .env im ersten Commit
git add .
git commit -q -m "notes: erster Stand"
git show --name-only --format= HEAD | grep envErwartet:
.env
.env.example
So beginnt fast jeder Secret-Vorfall in Git: git add .
im ersten Commit, bevor jemand an eine .gitignore gedacht
hat.
Fortschritt speichern? Kostenlos registrieren
Drill 3: .gitignore – und warum sie jetzt nicht hilft
cat > .gitignore <<'EOF'
# .gitignore – was nie ins Repository gehört (Tag 12)
# Secrets und lokale Werte (.env.example ist die Vorlage und darf rein)
*.env
.env
.env.*
!.env.example
*.pem
*.key
secrets/
.npmrc
# Abhängigkeiten und Build-Artefakte
node_modules/
dist/
.venv/
__pycache__/
*.pyc
*.test
# Betriebssystem und Editor
.DS_Store
EOF
git status --short
git check-ignore -v .env; echo "Exit-Code: $?"Erwartet:
?? .gitignore
Exit-Code: 1
git status zeigt keine Änderung an der
.env, und check-ignore sagt „nicht ignoriert”.
Warum? .gitignore wirkt nur auf Dateien, die Git noch
nicht verfolgt. Die .env ist seit Drill 2
im Index. Ob die Regel grundsätzlich passt, verrät
--no-index, und welche verfolgten Dateien eigentlich
ignoriert wären, zeigt ls-files:
git check-ignore -v --no-index .env
git ls-files --cached --ignored --exclude-standardErwartet:
.gitignore:4:.env .env
.env
Die zweite Zeile ist deine Aufräumliste. In einem fremden Repository ist das der schnellste Gesundheitscheck.
Fortschritt speichern? Kostenlos registrieren
Drill 4: Aufräumen, Historie, rotieren
git rm --cached .env
git add .gitignore
git status --short
git commit -q -m "chore: .env raus, .gitignore rein"
ls .envErwartet:
rm '.env'
D .env
A .gitignore
.env
--cached entfernt die Datei nur aus dem Index, deine
Arbeitskopie bleibt. Ist der Key damit aus Git verschwunden?
git log --oneline -- .env
git log -S lab-api-key-123 --format='%h %s'
git show HEAD~1:.envErwartet (Hashes weichen ab):
a78d05a chore: .env raus, .gitignore rein
ac09be7 notes: erster Stand
a78d05a chore: .env raus, .gitignore rein
ac09be7 notes: erster Stand
# Lokale Entwicklungswerte – Lab-Werte, niemals produktiv verwenden
NOTES_API_KEY=lab-api-key-123
Nein. git log -S findet jeden Commit, der die Zahl der
Vorkommen ändert: den, der den Key brachte, und den, der ihn entfernte.
Jeder Klon enthält beide. Deshalb gilt die Reihenfolge: zuerst
rotieren, dann Historie bereinigen.
cat > .env <<'EOF'
# Lokale Entwicklungswerte – Lab-Werte, niemals produktiv verwenden
NOTES_API_KEY=lab-api-key-456
EOF
git status --shortErwartet: keine Ausgabe. Die neue .env ist ignoriert,
der alte Key ist wertlos.
Achtung: Die Historie umschreiben kann
git filter-repo(separates Werkzeug), etwa mitgit filter-repo --invert-paths --path .env. Das ändert alle Commit-Hashes; danach müssen alle Klone neu geklont werden, Forks und Caches der Git-Plattform behalten den Key trotzdem. Rotieren ist nie optional.
Fortschritt speichern? Kostenlos registrieren
Drill 5: Muster prüfen statt raten
Leg ein paar typische Kandidaten an und frag Git, welche Regel greift:
mkdir -p secrets notes-web/node_modules/demo notes-web/dist
printf '%s\n' lab-api-key-456 > secrets/notes_api_key.txt
touch .env.local lab.env notes-web/.npmrc notes-web/dist/app.js \
notes-web/node_modules/demo/index.js notes-api/notes-api.test
git check-ignore -v .env .env.local lab.env secrets/notes_api_key.txt \
notes-web/.npmrc notes-web/dist/app.js notes-api/notes-api.test notes-api/main.goErwartet:
.gitignore:4:.env .env
.gitignore:5:.env.* .env.local
.gitignore:3:*.env lab.env
.gitignore:9:secrets/ secrets/notes_api_key.txt
.gitignore:10:.npmrc notes-web/.npmrc
.gitignore:13:dist/ notes-web/dist/app.js
.gitignore:17:*.test notes-api/notes-api.test
main.go fehlt in der Liste: nicht ignoriert. Die Muster
ohne / in der Mitte gelten in jeder Tiefe,
notes-web/.npmrc trifft also .npmrc. Den
Gesamtüberblick liefert:
git status --short --ignoredErwartet:
!! .env
!! .env.local
!! lab.env
!! notes-api/notes-api.test
!! notes-web/.npmrc
!! notes-web/dist/
!! notes-web/node_modules/
!! secrets/
Zwei Fallen. Erstens die Ausnahme !.env.example: Mit
-v meldet check-ignore auch negierte Treffer
und endet dann mit Exit 0, obwohl die Datei nicht
ignoriert ist. In Skripten nimmst du -q:
git check-ignore -v --no-index .env.example; echo "Exit-Code: $?"
git check-ignore -q --no-index .env.example; echo "Exit-Code: $?"Erwartet:
.gitignore:6:!.env.example .env.example
Exit-Code: 0
Exit-Code: 1
Zweitens: Eine Datei in einem ignorierten Ordner lässt sich nicht zurückholen.
printf 'Hier liegen lokale Secret-Dateien.\n' > secrets/README.md
echo '!secrets/README.md' >> .gitignore
git check-ignore -v secrets/README.md
git restore .gitignore && rm secrets/README.mdErwartet:
.gitignore:9:secrets/ secrets/README.md
Git betritt secrets/ gar nicht erst, die Ausnahme wird
nie geprüft. Wer eine README im Secret-Ordner will, schreibt
secrets/* statt secrets/ und dahinter
!secrets/README.md.
Fortschritt speichern? Kostenlos registrieren
Drill 6: .dockerignore – gleiche Absicht, andere Regeln
Deine Projekt-.dockerignore von Tag 3 enthält
.env und .env.*. Jetzt legt jemand für
go run eine Dienst-.env an:
printf '%s\n' NOTES_API_KEY=lab-api-key-456 > notes-api/.env
git check-ignore -q notes-api/.env && echo "Git: ignoriert"
rm -rf /tmp/notes-ctx
printf 'FROM scratch\nCOPY . /\n' \
| docker build -q -f - -o type=local,dest=/tmp/notes-ctx . >/dev/null
find /tmp/notes-ctx -name '*.env*' -o -name secretsErwartet (gekürzt, kann je nach Version abweichen):
Git: ignoriert
/tmp/notes-ctx/secrets
/tmp/notes-ctx/notes-api/.env
/tmp/notes-ctx/lab.env
/tmp/notes-ctx/.env.example
Der Trick aus Tag 3: Ein FROM scratch mit
COPY . / kopiert genau das, was beim Builder ankommt, und
-o type=local schreibt es nach /tmp/notes-ctx.
Neben der Dienst-.env sind auch lab.env und
secrets/ drin. Warum landet die Dienst-.env im
Kontext? In .gitignore gilt ein Muster ohne /
in jeder Tiefe. In .dockerignore gilt jedes Muster ab der
Wurzel des Kontexts; für alle Ebenen braucht es **/. Die
finale Projekt-.dockerignore deckt beides ab und schließt
auch .env.example aus – die Vorlage braucht kein Image:
cat > .dockerignore <<'EOF'
# .dockerignore im Projektordner – gilt, wenn der Projektordner der Build-Kontext ist.
# Muster gelten ab der Kontext-Wurzel: Für alle Ebenen braucht es **/.
# Secrets und lokale Werte (auch .env.example: gehört nicht ins Image)
**/.env*
**/*.env
**/secrets
**/*.pem
**/*.key
**/.npmrc
# Repository, Build-Dateien, Doku
.git
**/.gitignore
**/Dockerfile*
**/.dockerignore
**/*.md
compose.yaml
.hadolint.yaml
# Abhängigkeiten und Artefakte, die der Build selbst erzeugt
**/node_modules
**/dist
**/.venv
**/__pycache__
**/*.pyc
**/*.test
**/.DS_Store
EOF
rm -rf /tmp/notes-ctx
printf 'FROM scratch\nCOPY . /\n' \
| docker build -q -f - -o type=local,dest=/tmp/notes-ctx . >/dev/null
find /tmp/notes-ctx -name '*.env*' -o -name secrets | wc -l
find /tmp/notes-ctx -type f | wc -lErwartet (gekürzt, kann je nach Version abweichen):
0
12
Dateizahlen und Größen weichen bei dir ab. Die
Dienst-.dockerignore-Dateien bekommen dieselben
Secret-Muster. Übernimm sie aus dem Begleitcode und vergleiche mit
deinem Stand von Tag 6:
for d in notes-api notes-worker notes-web; do
cp "$LAB/code/tag12/notes/$d/.dockerignore" "$d/"
done
grep -c -E '^\*\*/(\.env\*|\*\.env|\*\.pem|\*\.key)$' \
notes-api/.dockerignore notes-worker/.dockerignore notes-web/.dockerignoreErwartet:
notes-api/.dockerignore:4
notes-worker/.dockerignore:4
notes-web/.dockerignore:4
| Datei | .env in Unterordnern |
.env.example |
node_modules/ |
|---|---|---|---|
.gitignore |
.env genügt |
!.env.example: ins Repo |
in jeder Tiefe |
.dockerignore |
braucht **/.env |
auch ausschließen | nur mit **/ |
Tipp: Eine
.gitignorelässt sich nicht einfach als.dockerignorekopieren. Führende und abschließende/ignoriert Docker,node_modules/heißt dort nur „node_modulesim Wurzelordner”.
Fortschritt speichern? Kostenlos registrieren
Drill 7: Compose liest .env – zweimal
Die erste compose.yaml des Buchs. Sie macht nur, was du
für Secrets brauchst:
cat > compose.yaml <<'EOF'
# compose.yaml – erste Version (Tag 12): nur so viel Compose, wie Secrets brauchen.
# Die .env im Projektordner liest Compose für ${…} (Interpolation);
# env_file: .env legt ihren Inhalt zusätzlich in die Container-Umgebung.
name: notes
services:
notes-api:
build: notes-api
image: notes-api:tag12
container_name: notes-api
env_file: .env
ports:
- "127.0.0.1:8080:8080"
notes-worker:
build: notes-worker
image: notes-worker:tag12
container_name: notes-worker
env_file: .env
environment:
NOTES_API_URL: http://notes-api:8080
INTERVAL: ${WORKER_INTERVAL:-10}
depends_on:
- notes-api
notes-web:
build: notes-web
image: notes-web:tag12
container_name: notes-web
env_file: .env
environment:
NOTES_API_URL: http://notes-api:8080
ports:
- "127.0.0.1:3000:3000"
depends_on:
- notes-api
EOF
docker compose config | grep -E 'NOTES_API_KEY|INTERVAL'Erwartet (gekürzt, kann je nach Version abweichen):
NOTES_API_KEY: lab-api-key-456
NOTES_API_KEY: lab-api-key-456
INTERVAL: "10"
NOTES_API_KEY: lab-api-key-456
docker compose config zeigt das fertige Modell:
${WORKER_INTERVAL:-10} ist aufgelöst, und der Inhalt jeder
env_file steht als environment im Klartext da.
Praktisch zum Debuggen, fatal im CI-Log oder in einem Ticket. Ohne Werte
geht es so:
docker compose config --no-interpolate --no-env-resolution \
| grep -E -A2 'env_file|INTERVAL' | head -6
docker compose config --no-interpolate --no-env-resolution | grep -c lab-api-keyErwartet (gekürzt, kann je nach Version abweichen):
env_file:
- path: /Users/du/docker-lab/tag12/.env
required: true
--
INTERVAL: ${WORKER_INTERVAL:-10}
0
--no-env-resolution lässt env_file als
Verweis stehen, --no-interpolate die
${…}-Ausdrücke. Ein drittes Leck ist
--environment: Es druckt alle Variablen, die Compose für
die Interpolation kennt, aus Shell und .env.
Und docker run --env-file? Gleiche Datei, anderer
Parser. Ein Kommentar am Zeilenende zeigt den Unterschied:
printf '%s\n' 'NOTES_API_KEY=lab-api-key-456 # Lab-Wert' > lab.env
docker run --rm --env-file lab.env golang:1.27-alpine printenv NOTES_API_KEY
docker compose --env-file lab.env config --environment | grep '^NOTES_API_KEY'
rm lab.envErwartet (gekürzt, kann je nach Version abweichen):
lab-api-key-456 # Lab-Wert
NOTES_API_KEY=lab-api-key-456
Für docker run --env-file ist ein # mitten
in der Zeile Teil des Werts. Compose behandelt # nach einem
Wert ohne Anführungszeichen als Kommentar. Halte .env
deshalb schlicht: eine Variable pro Zeile, Kommentare nur auf eigenen
Zeilen.
Fortschritt speichern? Kostenlos registrieren
Drill 8: Wer gewinnt?
Zwei getrennte Fragen: Woher kommt der Wert für ${…}
(Interpolation), und welcher Wert landet im Container?
worker='.services["notes-worker"].environment | {INTERVAL, WORKER_INTERVAL}'
api='.services["notes-api"].environment | {NOTES_API_KEY, WORKER_INTERVAL}'
docker compose config --format json | jq -c "$worker"
echo 'WORKER_INTERVAL=5' >> .env
docker compose config --format json | jq -c "$worker"
WORKER_INTERVAL=3 docker compose config --format json | jq -c "$worker"
NOTES_API_KEY=lab-api-key-123 docker compose config --format json | jq -c "$api"Erwartet (gekürzt, kann je nach Version abweichen):
{"INTERVAL":"10","WORKER_INTERVAL":null}
{"INTERVAL":"5","WORKER_INTERVAL":"5"}
{"INTERVAL":"3","WORKER_INTERVAL":"5"}
{"NOTES_API_KEY":"lab-api-key-456","WORKER_INTERVAL":"5"}
Was du gerade gesehen hast:
- Interpolation: Shell vor
--env-filevor.envvor dem Standardwert aus${VAR:-…}. Zeile 3:INTERVALfolgt der Shell. env_file: .envschickt jede Zeile in jeden Dienst, der sie lädt – auchWORKER_INTERVALannotes-api. Die.envhat zwei Rollen.- Eine Shell-Variable ändert keinen Wert aus
env_file:WORKER_INTERVALbleibt in Zeile 3 bei5, und der alte Key aus der Shell kommt in Zeile 4 nicht an. Die Shell greift nur, wocompose.yamlper${…}fragt.
| Rang | Quelle für den Container-Wert |
|---|---|
| 1 | docker compose run -e |
| 2 | environment: oder env_file: mit
interpoliertem Wert (${…}, Shell/.env) |
| 3 | environment: mit festem Wert |
| 4 | env_file: |
| 5 | ENV im Image |
Die Tabelle folgt der Compose-Doku („Environment variables precedence”). Zum Schluss die Zeile wieder entfernen und alles einmal starten:
grep -v '^WORKER_INTERVAL=' .env > .env.neu && mv .env.neu .env
WORKER_INTERVAL=2 docker compose up -d --build
curl -s -X POST localhost:3000/api/notes -H 'Content-Type: application/json' \
-d '{"text":"Tag 12 über notes-web"}'
sleep 3; docker compose logs notes-worker | tail -1
docker compose downErwartet (gekürzt, kann je nach Version abweichen):
✔ Container notes-api Started
✔ Container notes-worker Started
✔ Container notes-web Started
{"id":"2b7e…","text":"Tag 12 über notes-web"}
notes-worker | summary: 1 notes, 4 words
✔ Container notes-web Removed
✔ Container notes-worker Removed
✔ Container notes-api Removed
✔ Network notes_default Removed
Alle drei Dienste haben den Key aus env_file – und
docker inspect zeigt ihn bei jedem (Tag 11, Drill 3). Tag
14 ersetzt ihn durch eine Secret-Datei.
Fortschritt speichern? Kostenlos registrieren
Kontrollpunkt
Git ignoriert die .env:
cd ~/docker-lab/tag12
git check-ignore -v .envErwartet:
.gitignore:4:.env .env
Die Vorlage .env.example bleibt sichtbar:
git check-ignore --no-index .env.example; echo "Exit: $?"Erwartet:
Exit: 1
Keine ignorierte Datei mehr im Index:
git ls-files --cached --ignored --exclude-standardErwartet: keine Ausgabe.
Der Key ist rotiert:
grep NOTES_API_KEY .envErwartet:
NOTES_API_KEY=lab-api-key-456
Die .dockerignore greift in jeder Tiefe:
grep -x '\*\*/.env\*' .dockerignoreErwartet:
**/.env*
Die sichere config-Ausgabe enthält keinen Key:
docker compose config --no-interpolate --no-env-resolution | grep -c lab-api-keyErwartet:
0
Challenge
Schreib einen Git-Hook .git/hooks/pre-commit, der den
Commit abbricht, wenn eine gestagte Datei .env oder
.env.* heißt (außer .env.example) oder einen
Wert nach dem Muster lab-api-key-<Ziffern> enthält.
Teste ihn mit git add -f .env, mit einer Doku-Datei, die
einen Key zitiert, und mit einem harmlosen Commit.
Hinweis:
git diff --cached --name-only -z liefert die gestagten
Dateien, git show ":<pfad>" ihren gestagten Inhalt –
nicht den in der Arbeitskopie.
Lösung
Die Datei liegt auch unter
~/docker-lab/code/tag12/pre-commit.
cat > .git/hooks/pre-commit <<'EOF'
#!/usr/bin/env bash
# pre-commit – bricht den Commit ab, wenn .env-Dateien oder Lab-Keys gestagt sind.
# Installieren: cp pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
set -euo pipefail
muster='lab-api-key-[0-9]+'
fail=0
while IFS= read -r -d '' f; do
case "$(basename "$f")" in
.env.example) ;;
.env | .env.*)
echo "✘ $f: .env-Dateien gehören nicht ins Repository"
fail=1
;;
esac
if git show ":$f" | grep -qE -- "$muster"; then
echo "✘ $f: enthält einen API-Key ($muster)"
fail=1
fi
done < <(git diff --cached --name-only -z --diff-filter=ACMR)
if [ "$fail" -ne 0 ]; then
echo "Commit abgebrochen."
exit 1
fi
EOF
chmod +x .git/hooks/pre-commitDrei Tests:
git add -f .env && git commit -q -m "test: .env"; echo "Exit-Code: $?"
git reset -q .env
echo 'curl -H "X-API-Key: lab-api-key-456" localhost:8080/notes' > HOWTO.md
git add HOWTO.md && git commit -q -m "docs: Howto"; echo "Exit-Code: $?"
git reset -q HOWTO.md && rm HOWTO.md
git add compose.yaml .dockerignore notes-*/.dockerignore
git commit -q -m "build: compose.yaml, finale .dockerignore"; echo "Exit-Code: $?"Erwartet:
✘ .env: .env-Dateien gehören nicht ins Repository
✘ .env: enthält einen API-Key (lab-api-key-[0-9]+)
Commit abgebrochen.
Exit-Code: 1
✘ HOWTO.md: enthält einen API-Key (lab-api-key-[0-9]+)
Commit abgebrochen.
Exit-Code: 1
Exit-Code: 0
--diff-filter=ACMR lässt gelöschte Dateien aus, sonst
schlüge git show fehl. Der Hook liegt in
.git/hooks und wird nicht mitcommittet; jeder im Team muss
ihn selbst installieren, und git commit --no-verify umgeht
ihn. Aufräumen:
rm -rf /tmp/notes-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
- Lokale Hooks sind eine Komfortschicht. Verbindlich ist erst der Push-Schutz der Plattform (GitHub Secret Scanning mit Push Protection, GitLab Secret Push Protection) plus ein Secret-Scan in der Pipeline.
- Für Hooks im Team gibt es fertige Scanner, etwa gitleaks
(
brew install gitleaks, Hook über das pre-commit-Framework). Das Projekt ist laut README funktional abgeschlossen und bekommt nur noch Sicherheitsupdates. - Ein Key in der Git-Historie ist kompromittiert, auch in einem
privaten Repository: rotieren, dann mit
git filter-repobereinigen, Force-Push abstimmen, Klone und Forks einsammeln. .envist ein Entwickler-Werkzeug. In Produktion kommen Secrets aus einem Secret-Store, siehe „OpenBao-Secrets zum Anfassen”.docker compose configgehört in CI nur mit--quietoder mit--no-interpolate --no-env-resolutionins Log.