Docker Compose: Umgebungsvariablen & .env-Datei nutzen

Passwörter, Ports und Pfade gehören nicht fest in die docker-compose.yml – sie gehören in Umgebungsvariablen. In dieser Anleitung zeigen wir dir, wie du Umgebungsvariablen in Docker Compose richtig einsetzt: den Unterschied zwischen environment, env_file und der .env-Datei sowie die praktische Variablen-Substitution.

Passwörter, API-Schlüssel und Konfigurationswerte gehören nicht fest in die docker-compose.yml – sie ändern sich je nach Umgebung und dürfen nicht im Klartext im Repository landen. Genau dafür gibt es Umgebungsvariablen und die .env-Datei. In dieser Anleitung lernst du, wie du Werte sauber aus deinem Compose-Setup auslagerst, zwischen den verschiedenen Mechanismen unterscheidest und sensible Daten vor versehentlicher Veröffentlichung schützt.

Warum Umgebungsvariablen?

Umgebungsvariablen trennen die Konfiguration von der Anwendung. Das hat zwei große Vorteile: Du kannst dieselbe Compose-Datei für Test und Produktion nutzen (nur mit anderen Werten), und du hältst sensible Daten wie Passwörter aus der versionierten Datei heraus. Falls du Compose noch einrichten musst, hilft Docker Compose installieren.

Variante 1: environment direkt im Compose-File

Am direktesten definierst du Variablen im environment-Block eines Dienstes. Diese werden in den Container hineingereicht:

services:
  datenbank:
    image: postgres:16
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: geheim
      POSTGRES_DB: meineapp

services:
  datenbank:
    image: postgres:16
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD: geheim
      POSTGRES_DB: meineapp

Das ist übersichtlich, aber Passwörter stehen im Klartext in der Datei – für echte Geheimnisse nicht ideal.

Variante 2: Auslagern in eine env_file

Sauberer ist es, die Variablen in eine eigene Datei auszulagern und per env_file einzubinden. Lege z. B. eine Datei db.env an:

POSTGRES_USER=admin
POSTGRES_PASSWORD=geheim
POSTGRES_DB=meineapp

POSTGRES_USER=admin
POSTGRES_PASSWORD=geheim
POSTGRES_DB=meineapp

Und binde sie im Dienst ein:

services:
  datenbank:
    image: postgres:16
    env_file:
      - db.env

services:
  datenbank:
    image: postgres:16
    env_file:
      - db.env

Die Werte aus db.env landen als Umgebungsvariablen im Container. Diese Datei nimmst du dann von der Versionsverwaltung aus (siehe unten).

Variante 3: Die .env-Datei für Variablen-Substitution

Hier lauert die häufigste Verwechslung. Die speziell benannte Datei .env im Projektverzeichnis wird von Compose automatisch geladen – aber für einen anderen Zweck: Ihre Werte ersetzen Platzhalter innerhalb der Compose-Datei selbst. Lege eine .env an:

NGINX_PORT=8080
POSTGRES_VERSION=16

NGINX_PORT=8080
POSTGRES_VERSION=16

Und referenziere die Werte in der docker-compose.yml mit ${...}:

services:
  web:
    image: nginx:latest
    ports:
      - "${NGINX_PORT}:80"
  datenbank:
    image: postgres:${POSTGRES_VERSION}

services:
  web:
    image: nginx:latest
    ports:
      - "${NGINX_PORT}:80"
  datenbank:
    image: postgres:${POSTGRES_VERSION}

So passt du Ports oder Versionen zentral an einer Stelle an. Der Unterschied in einem Satz: .env ersetzt Platzhalter in der Compose-Datei, env_file setzt Variablen im Container.

Werte prüfen

Ob die Substitution wie erwartet greift, siehst du, ohne etwas zu starten. Der folgende Befehl zeigt die fertig aufgelöste Konfiguration:

docker compose config

docker compose config

Secrets nicht ins Repository

Ganz wichtig: Dateien mit Passwörtern gehören nicht in ein öffentliches Git-Repository. Trage sie in die .gitignore ein:

.env
*.env

.env
*.env

Für höhere Sicherheitsanforderungen bietet Docker zusätzlich das Konzept der Secrets, bei dem Geheimnisse als Dateien statt als Umgebungsvariablen bereitgestellt werden – ein sinnvoller nächster Schritt für produktive Setups.

.env, environment und env_file richtig unterscheiden

Docker Compose kennt mehrere Wege, Variablen zu setzen – und sie werden leicht verwechselt. Die .env-Datei füllt Platzhalter innerhalb der Compose-Datei, während environment und env_file Variablen in den Container hineinreichen. Dieser Unterschied ist die häufigste Fehlerquelle.

Rangfolge bei Konflikten

Wird dieselbe Variable an mehreren Stellen gesetzt, gewinnt die spezifischere Quelle. Diese Reihenfolge zu kennen erspart dir stundenlange Fehlersuche, wenn ein Wert scheinbar ignoriert wird.

• Ein Wert direkt unter environment: hat Vorrang vor env_file:.
• Auf der Shell gesetzte Variablen überschreiben die .env-Datei beim Parsen.
• Fehlt ein Platzhalter ganz, setzt Compose ihn auf einen leeren String – oft die Ursache stiller Fehler.

Sensible Daten schützen

Eine .env-Datei mit echten Passwörtern hat in keinem Git-Repository etwas verloren. Trage sie deshalb sofort in deine .gitignore ein und gib stattdessen eine .env.example mit leeren Platzhaltern weiter. So wissen andere, welche Werte nötig sind, ohne dass Geheimnisse durchsickern.

Für höhere Sicherheitsanforderungen bietet Docker außerdem Secrets. Anders als Umgebungsvariablen werden sie nicht in der Prozessliste oder in docker inspect sichtbar, sondern als Datei in den Container gemountet – die sauberere Lösung für produktive Zugangsdaten. Der Aufwand lohnt sich vor allem dort, wo mehrere Personen Zugriff auf den Host haben, denn Umgebungsvariablen lassen sich von jedem auslesen, der Container inspizieren darf.

Ein oft übersehenes Detail ist die Typisierung: In der .env-Datei ist alles ein String. Werte wie true oder Zahlen werden also als Text übergeben, was manche Anwendungen anders interpretieren, als du erwartest. Setze Werte mit Sonderzeichen oder Leerzeichen sicherheitshalber in Anführungszeichen und vermeide Leerzeichen um das Gleichheitszeichen, da Compose die Zeile sonst nicht sauber parst. Wer diese kleinen Regeln kennt, spart sich viele schwer auffindbare Konfigurationsfehler.

Häufige Fragen

Die häufigsten Fragen zu Umgebungsvariablen in Docker Compose.

Warum wird meine Variable nicht ersetzt?

Meist liegt die .env-Datei nicht im selben Verzeichnis wie die Compose-Datei oder der Platzhalter ist falsch geschrieben. Compose sucht die .env standardmäßig neben der docker-compose.yml.

Sind Umgebungsvariablen sicher für Passwörter?

Nur bedingt. Sie tauchen in docker inspect und teils in Logs auf. Für echte Geheimnisse solltest du Docker Secrets oder ein externes Vault-System verwenden.

Kann ich mehrere .env-Dateien nutzen?

Ja, über die Option --env-file beim docker compose-Aufruf lädst du gezielt eine bestimmte Datei, etwa für Staging und Produktion getrennt.

Fazit

Mit Umgebungsvariablen machst du deine Compose-Setups flexibel und sicherer. Merke dir die drei Werkzeuge: environment für einzelne Werte, env_file zum Auslagern in den Container und die .env-Datei für die Substitution in der Compose-Datei. Halte Geheimnisse per .gitignore aus dem Repository heraus. Passend weiter geht es mit Docker Volumes und Restart-Policies.