Zum Inhalt springen
Trainingslager IT-Trainingslager

Tag 12: .env, .gitignore und .dockerignore – das Dreieck

Ziel: Die .env aus Git und Build-Kontext heraushalten, einen schon committeten Key sauber entfernen und verstehen, wie Compose die .env liest. · Dauer: ca. 75 min · Voraussetzung: Tag 11

Briefing

  • .env hält lokale Werte, auch Secrets. Sie bleibt auf deinem Rechner.
  • .env.example nennt alle Variablen ohne Werte und kommt ins Repository.
  • .gitignore hält die .env aus Git, .dockerignore aus dem Build-Kontext. Gleiche Absicht, unterschiedliche Mustersyntax.
  • Compose liest die .env von selbst, aber nur für ${…} in compose.yaml. In den Container kommt sie erst über env_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 --short

Erwartet:

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 env

Erwartet:

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

Erwartet:

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

Erwartet:

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:.env

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

Erwartet: keine Ausgabe. Die neue .env ist ignoriert, der alte Key ist wertlos.

Achtung: Die Historie umschreiben kann git filter-repo (separates Werkzeug), etwa mit git 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.go

Erwartet:

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

Erwartet:

!! .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.md

Erwartet:

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

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

Erwartet (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/.dockerignore

Erwartet:

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 .gitignore lässt sich nicht einfach als .dockerignore kopieren. Führende und abschließende / ignoriert Docker, node_modules/ heißt dort nur „node_modules im 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-key

Erwartet (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.env

Erwartet (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-file vor .env vor dem Standardwert aus ${VAR:-…}. Zeile 3: INTERVAL folgt der Shell.
  • env_file: .env schickt jede Zeile in jeden Dienst, der sie lädt – auch WORKER_INTERVAL an notes-api. Die .env hat zwei Rollen.
  • Eine Shell-Variable ändert keinen Wert aus env_file: WORKER_INTERVAL bleibt in Zeile 3 bei 5, und der alte Key aus der Shell kommt in Zeile 4 nicht an. Die Shell greift nur, wo compose.yaml per ${…} 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 down

Erwartet (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 .env

Erwartet:

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

Erwartet: keine Ausgabe.

Der Key ist rotiert:

grep NOTES_API_KEY .env

Erwartet:

NOTES_API_KEY=lab-api-key-456

Die .dockerignore greift in jeder Tiefe:

grep -x '\*\*/.env\*' .dockerignore

Erwartet:

**/.env*

Die sichere config-Ausgabe enthält keinen Key:

docker compose config --no-interpolate --no-env-resolution | grep -c lab-api-key

Erwartet:

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-commit

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

Fortschritt 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-repo bereinigen, Force-Push abstimmen, Klone und Forks einsammeln.
  • .env ist ein Entwickler-Werkzeug. In Produktion kommen Secrets aus einem Secret-Store, siehe „OpenBao-Secrets zum Anfassen”.
  • docker compose config gehört in CI nur mit --quiet oder mit --no-interpolate --no-env-resolution ins Log.