Eine Organisation mit zwanzig oder dreißig eigenständigen Anwendungen sammelt fast zwangsläufig ebenso viele .env-Dateien an: eine je Projekt, oft eine weitere je Umgebung. Ein Datenbankpasswort wandert dann per Slack-Nachricht oder USB-Stick von einer Entwicklerin zur nächsten, niemand kann im Nachhinein sagen, wer welchen Schlüssel überhaupt kennt, und die Rotation eines einzigen kompromittierten API-Schlüssels bedeutet, ihn in jeder Kopie einzeln zu ersetzen. Genau dieses Sammelsurium ersetzt eine zentrale Geheimnisverwaltung: ein einziger verschlüsselter Speicher für alle Zugangsdaten, aus dem jede Anwendung ihre Werte zur Laufzeit abruft, mit einem Protokoll, wer wann worauf zugegriffen hat.
Infisical ist dafür ein quelloffenes, selbst hostbares Werkzeug und löst damit ein anderes Problem als ein Secret-Scanner wie Gitleaks oder TruffleHog. Ein Scanner durchsucht Code und Commit-Historie nach einem Zugangsschlüssel, der bereits im Klartext irgendwo gelandet ist, und meldet den Fund, nachdem der Schaden im Grunde schon passiert ist. Infisical setzt davor an: Zugangsdaten liegen gar nicht erst verstreut in Dateien, sondern verschlüsselt in einem zentralen Projekt, und eine Anwendung bekommt sie erst beim Start als gewöhnliche Umgebungsvariable eingespeist. Beide Werkzeuge schließen sich nicht aus. Wer weiterhin Gitleaks vor jedem Commit laufen lässt, fängt damit die Fälle ab, in denen trotz Infisical aus Versehen ein Schlüssel in eine Datei gerät, während Infisical die Zahl dieser Gelegenheiten von vornherein senkt.
Systemvoraussetzungen
Eine selbst gehostete Infisical-Installation besteht aus wenigen Bausteinen, aber jeder davon muss zur aktuellen Version passen. Die folgende Tabelle nennt die Komponenten und wofür sie im Betrieb stehen.
| Komponente | Version oder Anforderung | Zweck |
|---|---|---|
| Infisical-Server (Backend) | Docker-Image infisical/infisical, aktuelle Version v0.163.0 (veröffentlicht am 26. August 2026) | Weboberfläche, REST-API und Ver- und Entschlüsselung der Secrets |
| PostgreSQL | Image postgres:14-alpine laut offizieller Docker-Compose-Datei, alternativ eine verwaltete Postgres-Instanz | Speichert Organisationen, Projekte, Umgebungen, Nutzer und die verschlüsselten Secrets |
| Redis | Offizielles redis-Image, alternativ eine verwaltete Redis-Instanz | Cache und Job-Queue für Hintergrundaufgaben wie Benachrichtigungen und geplante Rotationen |
ENCRYPTION_KEY | 16 Byte langer Hex-String, erzeugt mit openssl rand -hex 16 | Verschlüsselt alle gespeicherten Secrets; ohne diesen Wert lassen sie sich nicht mehr entschlüsseln |
AUTH_SECRET | 32 Byte langer Base64-String, erzeugt mit openssl rand -base64 32 | Signiert Sitzungen und Zugriffstoken |
| Infisical CLI | Version 0.43.125 oder neuer | Führt infisical run aus und speist Secrets in eine laufende Anwendung ein |
| Node.js-SDK | Paket @infisical/sdk | Bindet Secrets direkt in eine Node.js-Anwendung ein, ohne den Umweg über die CLI |
Systemarchitektur
Ein Secret ist in diesem Zusammenhang jede Zugangsinformation, die Zugriff auf ein System gewährt: ein Datenbankpasswort, ein API-Schlüssel oder ein OAuth-Token. Infisical ordnet jedes Secret einem Projekt zu, innerhalb des Projekts einer Umgebung (typischerweise dev, staging und prod) und innerhalb der Umgebung optional einem Ordner, der Secrets nach Dienst oder Zweck gruppiert und beliebig tief verschachtelt werden kann, etwa /billing-service/database. In der Oberfläche heißt dieser Ordner schlicht Folder, in der REST-API und in den CLI-Aufrufen taucht derselbe Wert als Parameter secretPath beziehungsweise als Flag --path auf. Eine Anwendung greift also nie auf "alle Secrets" zu, sondern immer auf genau den Ordner einer bestimmten Umgebung.
Der Zugriff selbst läuft über zwei unterschiedliche Wege, je nachdem, wer oder was die Secrets abruft. Eine Entwicklerin meldet sich mit ihrem Benutzerkonto an. Eine Anwendung, ein Build-Server oder eine CI-Pipeline meldet sich stattdessen als sogenannte Machine Identity an, ein eigenständiges Konto für Software statt für Menschen, das sich über ein Client-ID/Client-Secret-Paar authentifiziert und dafür ein kurzlebiges Zugriffstoken erhält. Beide Kontoarten bekommen dieselben vier eingebauten Rollen zugewiesen: Admin, Member, Viewer und No Access, jeweils bezogen auf ein Projekt.
flowchart TD
A[Team pflegt ein Secret in einem Ordner der Umgebung prod] --> B[Infisical-Server verschluesselt und speichert das Secret in Postgres]
B --> C[Anwendung 1 startet mit infisical run]
B --> D[Anwendung 2 bindet das Node.js-SDK ein]
B --> E[CI-Pipeline meldet sich als Machine Identity an]
C --> F[CLI holt Secrets fuer Projekt, Umgebung und Ordner ab]
D --> G[SDK ruft dieselben Secrets ueber die REST-API ab]
E --> H[Pipeline erhaelt ein kurzlebiges Zugriffstoken]
F --> I[CLI uebergibt die Secrets als Umgebungsvariablen an den Kindprozess]
G --> J[Anwendung liest die Werte direkt aus dem SDK-Client]
H --> K[Pipeline nutzt die Secrets fuer den Build- oder Deploy-Schritt]
I --> L[Jeder Zugriff wird im Audit-Log mit Akteur und Zeitpunkt vermerkt]
J --> L
K --> L
M[Admin rotiert ein kompromittiertes Secret im Dashboard] --> B
Wird ein Secret rotiert, ändert sich an diesem Ablauf nichts weiter, als dass Schritt B einen neuen Wert liefert. Jede Anwendung, die ihre Secrets beim Start über die CLI oder das SDK abruft, bekommt beim nächsten Neustart automatisch den neuen Wert, ohne dass irgendwo eine Datei von Hand nachgezogen werden müsste. Genau diese Eigenschaft ist der praktische Vorteil gegenüber verstreuten .env-Dateien: Eine Rotation ist ein einziger Vorgang an einer Stelle statt einer Kopieraktion über zwanzig Repositories.
Schritt-für-Schritt-Umsetzung
Infisical per Docker Compose selbst hosten
Infisical stellt eine fertige Docker-Compose-Datei für den produktiven Betrieb bereit. Sie startet die drei Container aus der Tabelle oben und liest ihre Konfiguration aus einer .env-Datei im selben Verzeichnis.
curl -o docker-compose.prod.yml https://raw.githubusercontent.com/Infisical/infisical/main/docker-compose.prod.yml
curl -o .env https://raw.githubusercontent.com/Infisical/infisical/main/.env.example
chmod 600 .env
# In der .env-Datei mindestens setzen:
ENCRYPTION_KEY=$(openssl rand -hex 16)
AUTH_SECRET=$(openssl rand -base64 32)
SITE_URL=https://secrets.beispiel-firma.de
docker compose -f docker-compose.prod.yml up -d
Der erste Aufruf der Weboberfläche fragt nach einem neuen Konto, und genau dieses erste Konto wird automatisch zum Administrator der gesamten Instanz. Der Wert von ENCRYPTION_KEY gehört sofort in eine separate Sicherung: Geht er verloren, lässt sich kein einziges gespeichertes Secret mehr entschlüsseln, auch nicht mit Zugriff auf die Datenbank selbst.
Projekt, Umgebung und Ordner anlegen
Nach der Anmeldung legt die Administratorin für jede Anwendung ein eigenes Projekt an. Innerhalb eines Projekts bringt Infisical von Haus aus drei Umgebungen mit, üblicherweise development, staging und production, die sich umbenennen oder um weitere ergänzen lassen. Innerhalb einer Umgebung sortiert ein Ordner die Secrets nach Zuständigkeit, etwa getrennt nach Datenbank, Zahlungsanbieter und Mailversand.
- Organisation. Der äußerste Rahmen, meist eine Firma oder ein Team, und Träger der übergreifenden Mitgliederliste.
- Projekt. Eine einzelne Anwendung oder ein zusammengehöriger Dienst, etwa der Zahlungsdienst oder das Kundenportal.
- Umgebung. Der Betriebszustand innerhalb eines Projekts, zum Beispiel dev, staging und prod, mit jeweils eigenen Werten für dieselben Schlüssel.
- Ordner. Eine hierarchische Gruppierung innerhalb einer Umgebung, beliebig tief verschachtelbar, etwa
/billing-service/databasefür alle Datenbank-Zugangsdaten dieses Diensts.
Eine CI-Pipeline oder ein Server braucht anschließend eine eigene Machine Identity, angelegt unter Projekt, Zugriffskontrolle und Machine Identities. Für die Authentifizierung dieser Identität eignet sich die eingebaute Methode Universal Auth: Die Pipeline übermittelt ein Client-ID/Client-Secret-Paar und erhält dafür ein Zugriffstoken mit begrenzter Lebensdauer zurück, ohne dass ein statischer, dauerhaft gültiger Schlüssel irgendwo abgelegt werden muss.
Secrets per CLI in eine laufende Anwendung einspeisen
Der Befehl infisical run holt die Secrets für ein angegebenes Projekt, eine Umgebung und einen Ordner ab und startet den dahinterstehenden Befehl mit genau diesen Werten als Umgebungsvariablen, ohne je eine Datei auf die Festplatte zu schreiben.
# Lokale Entwicklung, Anmeldung ueber das persoenliche Konto
infisical run --env=dev --path="/billing-service" -- npm run dev
# CI-Pipeline oder Server, Anmeldung als Machine Identity
export INFISICAL_TOKEN=$(infisical login --method=universal-auth \
--client-id="$INFISICAL_CLIENT_ID" \
--client-secret="$INFISICAL_CLIENT_SECRET" --plain)
infisical run --env=prod --path="/billing-service" --projectId="$INFISICAL_PROJECT_ID" \
-- node server.js
Die Anwendung selbst braucht dafür keine einzige Codezeile zu ändern: Sie liest process.env.DATABASE_URL oder das Äquivalent in ihrer Sprache genauso, wie sie es bei einer klassischen .env-Datei täte. Der Unterschied liegt allein darin, woher der Wert kommt, nicht darin, wie die Anwendung ihn abruft. Die Option --watch startet den Befehl zusätzlich automatisch neu, sobald sich ein Secret in Infisical ändert, was sich für lang laufende lokale Entwicklungsserver anbietet.
Secrets per Node.js-SDK statt CLI laden
Wo ein Prozess dauerhaft läuft und selbst entscheiden soll, wann er neue Werte abruft, ersetzt das offizielle Node.js-SDK die CLI. Es meldet sich ebenfalls über Universal Auth an und liest Secrets danach direkt über die REST-API.
npm install @infisical/sdk
import { InfisicalSDK } from "@infisical/sdk";
const client = new InfisicalSDK({
siteUrl: "https://secrets.beispiel-firma.de",
});
await client.auth().universalAuth.login({
clientId: process.env.INFISICAL_CLIENT_ID,
clientSecret: process.env.INFISICAL_CLIENT_SECRET,
});
const databaseUrl = await client.secrets().getSecret({
projectId: process.env.INFISICAL_PROJECT_ID,
environment: "prod",
secretPath: "/billing-service",
secretName: "DATABASE_URL",
});
Dieser Weg eignet sich besonders für Anwendungen, die ohnehin über eine eigene Startroutine verfügen und dort Secrets gezielt nachladen wollen, statt sie pauschal beim Prozessstart über infisical run zu erhalten.
Häufige Fehlerquellen
- Alte .env-Datei bleibt neben der Infisical-Anbindung liegen. Wird bei der Umstellung nur der Startbefehl in einer von mehreren Umgebungen geändert, ein Cron-Job oder ein systemd-Dienst aber weiter direkt gestartet, liest dieser Pfad weiterhin die alte Datei. Wird das Secret danach in Infisical rotiert, arbeitet genau dieser Dienst still mit dem alten, längst ungültig gemachten Wert weiter, ohne dass ein Fehler sichtbar wird. Die Datei gehört nach abgeschlossener Umstellung gelöscht, nicht nur ungenutzt liegen gelassen, und jeder Startpfad einer Anwendung muss auf
infisical runoder das SDK umgestellt sein, nicht nur der Hauptprozess. - ENCRYPTION_KEY geht ohne Sicherung verloren. Wird der Server neu aufgesetzt oder die
.env-Datei des Hosts versehentlich überschrieben, ohne dass der Wert vorher gesichert wurde, lässt sich keines der gespeicherten Secrets mehr entschlüsseln, auch die Datenbank selbst bleibt dabei unbeschädigt. Der Wert gehört von Anfang an in einen eigenen, getrennt gesicherten Passwort-Tresor. - Beispielwerte aus der .env.example unverändert übernommen. Wer die heruntergeladene Vorlage direkt startet, ohne
ENCRYPTION_KEYundAUTH_SECRETdurch selbst erzeugte Zufallswerte zu ersetzen, betreibt eine Installation mit öffentlich bekannten Schlüsseln. Beide Werte müssen vor dem ersten Start durch die in der Tabelle oben genanntenopenssl-Befehle ersetzt werden. - Falscher oder fehlender --path bei infisical run. Zeigt der Ordnerpfad auf eine leere oder falsche Stelle, startet die Anwendung ohne Fehlermeldung mit leeren Umgebungsvariablen, weil die CLI schlicht keine Secrets an dieser Stelle findet. Der Pfad muss exakt dem Ordner entsprechen, in dem das Team die Secrets tatsächlich angelegt hat, und lässt sich vor dem produktiven Einsatz mit
infisical secrets --path="..."ohnerungegenprüfen. - Machine Identity bekommt die Rolle Admin statt einer eng gefassten Rolle. Eine CI-Pipeline, die nur den Deploy-Schritt eines einzigen Dienstes ausführt, braucht keinen Zugriff auf jede Umgebung jedes Projekts. Mit der Rolle Admin kann sie das trotzdem, und ein kompromittiertes Pipeline-Token setzt dann die gesamte Organisation aufs Spiel statt nur einen Ordner. Die Rolle Member oder eine über Additional Privileges eingeschränkte Rolle genügt für die meisten automatisierten Zugriffe.
- Audit-Log wird bei einer selbst gehosteten Installation ohne Lizenz erwartet. Das Audit-Log ist laut eigener Dokumentation kein Bestandteil der kostenlosen, selbst gehosteten Community-Version, sondern verlangt eine separate Enterprise-Lizenz. Wer die Nachvollziehbarkeit der Zugriffe für eine Prüfung oder ein Audit braucht, muss das vor dem Aufbau der Installation einplanen, nicht erst danach feststellen.
Häufig gestellte Fragen
Was unterscheidet Infisical von einem Secret-Scanner wie Gitleaks?
Infisical und ein Secret-Scanner wie Gitleaks lösen zwei unterschiedliche Probleme, die sich ergänzen, statt sich zu ersetzen. Gitleaks durchsucht Code und Commit-Historie nach einem Zugangsschlüssel, der bereits im Klartext irgendwo gelandet ist, und meldet den Fund erst danach. Infisical setzt davor an, indem Zugangsdaten von vornherein verschlüsselt in einem zentralen Projekt liegen und erst beim Start einer Anwendung als Umgebungsvariable eingespeist werden, sodass eine Datei mit Klartext-Secrets gar nicht erst entsteht. In einer Organisation mit vielen Repositories ist die Kombination beider Werkzeuge sinnvoll, weil ein Scanner weiterhin die Fälle abfängt, in denen trotz zentraler Verwaltung aus Versehen ein Wert in eine Datei gerät.
Welche Docker-Images und Datenbanken benötigt eine selbst gehostete Infisical-Installation?
Eine selbst gehostete Infisical-Installation benötigt drei Container: das Backend-Image infisical/infisical für Weboberfläche und API, PostgreSQL für Organisationen, Projekte und die verschlüsselten Secrets, sowie Redis für Cache und Job-Queue im Hintergrund. Die offizielle Docker-Compose-Datei setzt dafür konkret postgres:14-alpine und das offizielle redis-Image ein, beide lassen sich beim Einsatz einer verwalteten Datenbank auch durch externe Instanzen ersetzen. Zusätzlich verlangt der Start zwei selbst erzeugte Zufallswerte, ENCRYPTION_KEY und AUTH_SECRET, ohne die die Installation nicht hochfährt.
Wie liest eine Anwendung ihre Secrets aus Infisical, ohne eine lokale .env-Datei zu benötigen?
Eine Anwendung liest ihre Secrets aus Infisical, indem sie entweder über den Befehl infisical run --env=prod -- <startbefehl> gestartet wird oder das Node.js-SDK @infisical/sdk direkt einbindet. Im ersten Fall holt die CLI die Secrets für Projekt, Umgebung und Ordner ab und übergibt sie dem gestarteten Prozess als gewöhnliche Umgebungsvariablen, sodass der Anwendungscode unverändert bleibt. Im zweiten Fall meldet sich die Anwendung selbst über eine Machine Identity an und ruft einzelne Werte gezielt über die REST-API ab. In beiden Fällen liegt zu keinem Zeitpunkt eine Datei mit den Klartext-Werten auf der Festplatte.
Ist das Audit-Log bei einer selbst gehosteten Infisical-Installation kostenlos nutzbar?
Das Audit-Log ist bei einer selbst gehosteten Infisical-Installation nicht Teil der kostenlosen Community-Version, sondern verlangt laut eigener Dokumentation eine separate Enterprise-Lizenz. Es protokolliert dafür mehr als vierzig unterschiedliche Ereignistypen mit dem handelnden Konto, der genauen Aktion, der IP-Adresse und dem Zeitpunkt. Wer diese Nachvollziehbarkeit für eine interne Prüfung oder eine externe Zertifizierung braucht, sollte die Lizenzfrage vor dem Aufbau der Installation klären, weil eine nachträgliche Aktivierung keine rückwirkenden Protokolle für die Zeit davor liefert.