Zugangsdaten mit Docker Compose Secrets schützen¶

Veröffentlicht am 27. August 2026 · Geschätzte Lesezeit: 4 Minuten

Passwörter und API-Schlüssel gehören nicht direkt in eine compose.yaml. Docker Compose kann solche Werte aus getrennten Dateien nur den Containern bereitstellen, die sie wirklich benötigen. Die Umstellung dauert etwa 15 Minuten und lässt sich ohne Swarm-Modus durchführen.

Voraussetzungen

Ein Linux-Server mit Docker und dem Befehl docker compose
Ein vorhandener Compose-Stack mit einer Anwendung, die Datei-Geheimnisse unterstützt
Terminalzugriff auf den Server
Ein aktuelles Backup der Compose-Datei und der Anwendungsdaten

1. Unterstützung der Anwendung prüfen¶

Prüfe zuerst in der Dokumentation deines Container-Images, ob es eine Variable wie PASSWORD_FILE, TOKEN_FILE oder SECRET_FILE unterstützt. Das Suffix _FILE ist verbreitet, aber kein allgemeiner Docker-Standard.

Nicht blind übernehmen

Im folgenden Beispiel heißt die Variable APP_PASSWORD_FILE. Ersetze sie durch den genau dokumentierten Namen deiner Anwendung. Unterstützt das Image keine Datei-Variable, kann es den Inhalt unter /run/secrets/ nicht automatisch nutzen.

2. Compose-Datei sichern¶

Wechsle auf dem Server in den Ordner des vorhandenen Stacks. Ersetze <app-ordner> durch den tatsächlichen Pfad.

cd <app-ordner>

Lege eine Sicherung der Compose-Datei an. Falls deine Datei docker-compose.yml heißt, passe den Namen im Befehl an.

cp compose.yaml compose.yaml.vor-secrets

3. Geheimnis-Datei anlegen¶

Erstelle im Projektordner ein nur für den Besitzer zugängliches Verzeichnis.

install -d -m 700 secrets

Lege die Datei mit eingeschränkten Rechten an.

install -m 600 /dev/null secrets/app_password.txt

Öffne die Datei im Editor und trage nur das echte Passwort oder Token ein. Der Wert erscheint dadurch nicht im kopierten Befehl und nicht in der Shell-Historie.

nano secrets/app_password.txt

Speichere in Nano mit Strg+O, bestätige mit Enter und beende mit Strg+X.

Geheimnis nicht ausgeben

Prüfe die Datei nicht mit cat und füge ihren Inhalt niemals in Fehlermeldungen, Screenshots oder Support-Anfragen ein. Die Datei ist auf dem Host weiterhin im Klartext gespeichert und muss durch Dateirechte und sichere Backups geschützt werden.

4. Git vor dem Geheimnis schützen¶

Falls der Ordner mit Git verwaltet wird, ergänze die .gitignore. Dieser Block ist Dateiinhalt und wird in <app-ordner>/.gitignore eingefügt.

secrets/

Prüfe anschließend, ob die Datei bereits verfolgt wird. Eine leere Ausgabe ist das gewünschte Ergebnis.

git ls-files secrets/

Bereits eingecheckte Werte

.gitignore entfernt keine alten Git-Versionen. War ein echtes Passwort bereits im Repository, ändere es bei der Anwendung und bereinige die Historie getrennt.

5. Secret in Compose eintragen¶

Öffne die vorhandene Compose-Datei.

nano compose.yaml

Ergänze beim gewünschten Dienst den Zugriff auf das Secret und definiere es zusätzlich auf oberster Ebene. <vorhandenes-image> und <dienstname> stehen für deine bereits vorhandenen Werte; der Block ist ein Muster und ersetzt nicht den restlichen Stack.

services:
  <dienstname>:
    image: <vorhandenes-image>
    environment:
      APP_PASSWORD_FILE: /run/secrets/app_password
    secrets:
      - app_password

secrets:
  app_password:
    file: ./secrets/app_password.txt

Entferne danach die bisherige Passwortvariable mit dem Klartextwert. Docker Compose stellt die Datei im Container schreibgeschützt als /run/secrets/app_password bereit. Andere Dienste erhalten keinen Zugriff, solange das Secret dort nicht ausdrücklich eingetragen ist.

6. Konfiguration prüfen und Dienst neu erstellen¶

Lass Docker die Compose-Datei prüfen. Der Befehl wird im Projektordner ausgeführt und zeigt Strukturfehler, ohne den Secret-Inhalt auszugeben.

docker compose config --quiet

Ersetze <dienstname> durch den Namen unter services: und erstelle nur diesen Container neu.

docker compose up -d --force-recreate <dienstname>

Prüfe den Zustand des Stacks.

docker compose ps

Teste nur, ob die Datei im Container lesbar ist. Der Inhalt wird dabei nicht angezeigt.

docker compose exec <dienstname> test -r /run/secrets/app_password

Der Befehl bleibt bei Erfolg ohne Ausgabe. Sieh bei Problemen in die letzten Protokollzeilen, aber veröffentliche keine Ausgabe, die Zugangsdaten enthalten könnte.

docker compose logs --tail=50 <dienstname>

7. Backup und Rückweg¶

Sichere compose.yaml, die Secret-Datei und die Anwendungsdaten verschlüsselt auf einem zweiten Datenträger. Eine unverschlüsselte Kopie der Secret-Datei gehört nicht in eine normale Cloud-Freigabe.

Falls die Anwendung mit der Datei-Variable nicht startet, spiele zuerst die alte Compose-Datei zurück.

cp compose.yaml.vor-secrets compose.yaml

Erstelle den betroffenen Dienst anschließend neu.

docker compose up -d --force-recreate <dienstname>

Secret später wechseln

Ändere den Wert im Editor, starte den betroffenen Container mit --force-recreate neu und prüfe die Anmeldung. Bewahre den alten Wert nur so lange auf, bis die Funktionsprüfung abgeschlossen ist.

8. Typische Fehler¶

Variable wird ignoriert: Das Image unterstützt den verwendeten _FILE-Namen nicht.
Datei fehlt im Container: Das Secret wurde nur oben definiert, aber nicht beim Dienst freigegeben.
Anmeldung scheitert: Ein Zeilenumbruch oder Leerzeichen wurde mitgespeichert.
Permission denied: Die Anwendung verlangt einen anderen Zielnamen oder eigene Dateirechte; prüfe ihre Dokumentation.
Alter Wert bleibt aktiv: Der Container wurde nach der Änderung nicht neu erstellt.

9. Quellen und Video¶

Technischer Stand: 26. August 2026.

Fertig¶

Das Geheimnis steht nicht mehr direkt in der Compose-Datei und wird nur dem ausgewählten Container unter /run/secrets/app_password bereitgestellt. Eine erfolgreiche Anmeldung in der Anwendung und ein laufender Zustand in docker compose ps bestätigen die Umstellung.