OpenBao mit Docker unter Linux installieren: zentraler Secrets-Store unter MPL-2.0
OpenBao, der Linux-Foundation-Fork von HashiCorp Vault unter MPL-2.0, läuft per Docker Compose mit PostgreSQL-Backend. Die Anleitung zeigt compose.yaml, Unseal-Prozess, CLI und typische Fehler.
Werbung Mit * markierte Links sind Werbelinks: Bei einem Kauf erhalten wir eine Provision, der Preis bleibt gleich. Als Amazon-Partner verdiene ich an qualifizierten Verkäufen. Mehr dazu

OpenBao speichert Zugangsdaten, TLS-Zertifikate und dynamische Datenbankzugänge zentral und verschlüsselt (ein „Secrets-Store“). Das Projekt ist ein Fork von HashiCorp Vault, den die Linux Foundation betreut, nachdem HashiCorp 2023 die Lizenz auf BSL umgestellt hatte. OpenBao steht unter der MPL-2.0 und ist API-kompatibel zu Vault. Aktuell ist Version 2.7.1.
Voraussetzungen
- Linux-Host oder VM (Ubuntu 22.04/24.04, Debian 12 oder vergleichbar) mit Docker Engine 24+ und Compose Plugin v2 (Installation: Docker- und Docker-Compose-Grundlage), x86-64 oder ARM64
- Mindestens 512 MB RAM (empfohlen: 1 GB+), mindestens 1 GB freier Speicherplatz
- Netzwerkzugriff auf Port 8200/TCP (API); für Cluster-Replikation zusätzlich 8201/TCP
- Passwortmanager oder sicherer Speicher für Unseal-Schlüssel und Root-Token (z. B. Vaultwarden)
- Optional: Reverse Proxy (Traefik, Nginx, Caddy) für HTTPS, in Produktion Pflicht
Eckdaten: Image, Ports, Volumes und Umgebungsvariablen
| Parameter | Wert | Hinweis |
|---|---|---|
| Image | openbao/openbao:2.7.1 | Stable-Tag pinnen; Multi-Arch: amd64, arm64, armv6, s390x, riscv64, ppc64le |
| Alternatives Image | ghcr.io/openbao/openbao:2.7.1 | GitHub Container Registry |
| Port | 8200:8200 | API und (mit ui = true) Web-UI; 8201 nur für Multi-Node-HA |
| Volume config | ./config:/openbao/config | HCL/JSON-Konfiguration; vor dem ersten Start anlegen |
| Volume data | bao_data:/openbao/file | Datenverzeichnis für PebbleDB oder Raft; mit PostgreSQL ungenutzt |
| Volume logs | bao_logs:/openbao/logs | Audit-Logs; optional, aber empfohlen |
| Env: BAO_LOG_LEVEL | info | trace/debug/info/warn/error |
| Env: BAO_ADDR | http://127.0.0.1:8200 | Adresse für bao im Container, nötig wegen tls_disable |
| Capability | IPC_LOCK | Verhindert Swap-Auslagerung von Secrets (Pflicht) |
| User | openbao (non-root) | Volumes müssen schreibbar sein |
Schritt 1: Projektordner anlegen und vorbereiten
Legen Sie einen eigenen Ordner für OpenBao an, hier /opt/openbao/.
$ mkdir -p /opt/openbao/config
$ cd /opt/openbaoDie Named Volumes (postgres_data, bao_data, bao_logs) legt Docker selbst an.
ls -la /opt/openbao/: Sie sehen config/ als leeres Verzeichnis.
Schritt 2: .env-Datei anlegen
Passwörter und variable Parameter stehen in der .env-Datei, die nie ins Git-Repository gehört.
# /opt/openbao/.env: NICHT in Git einchecken!
POSTGRES_DB=openbao
POSTGRES_USER=openbao
POSTGRES_PASSWORD=SICHER_AENDERN
BAO_LOG_LEVEL=infoErsetzen Sie SICHER_AENDERN durch ein starkes, zufälliges Passwort. Enthält das Passwort Sonderzeichen wie @, / oder ?, müssen diese in der connection_url der config.hcl URL-kodiert werden (z. B. @ → %40). Sonst scheitert die Verbindung mit „invalid dsn“.
$ chmod 600 /opt/openbao/.envcat /opt/openbao/.env zeigt alle vier Variablen.
Schritt 3: Konfigurationsdatei config.hcl anlegen
Die Datei richtet das PostgreSQL-Storage-Backend ein und schaltet TLS am Listener ab, weil ein Reverse Proxy die Verschlüsselung übernimmt.
# /opt/openbao/config/config.hcl
storage "postgresql" {
connection_url = "postgres://openbao:SICHER_AENDERN@postgres:5432/openbao?sslmode=disable"
ha_enabled = "false"
}
listener "tcp" {
address = "0.0.0.0:8200"
tls_disable = "true"
}
api_addr = "http://0.0.0.0:8200"
ui = falseErsetzen Sie SICHER_AENDERN durch das Passwort aus Ihrer .env. Der Hostname postgres ist der Service-Name im Compose-Stack. ha_enabled = "false" passt für einen Einzelknoten. Mit ui = true erreichen Sie die Web-UI unter http://SERVER:8200/ui/. tls_disable = "true" ist nur hinter einem Reverse Proxy mit HTTPS vertretbar, sonst gehen Root-Token und Secrets im Klartext über das Netz.
cat /opt/openbao/config/config.hcl zeigt Storage-Block, Listener und api_addr vollständig.
Schritt 4: compose.yaml erstellen und Stack starten
Der Stack besteht aus PostgreSQL als Storage-Backend und OpenBao. Der Healthcheck in depends_on sorgt dafür, dass PostgreSQL bereit ist, bevor OpenBao startet.
# /opt/openbao/compose.yaml
services:
postgres:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_DB: ${POSTGRES_DB:-openbao}
POSTGRES_USER: ${POSTGRES_USER:-openbao}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?POSTGRES_PASSWORD muss in .env gesetzt sein}
volumes:
- postgres_data:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-openbao} -d ${POSTGRES_DB:-openbao}"]
interval: 10s
timeout: 5s
retries: 5
openbao:
image: openbao/openbao:2.7.1
restart: unless-stopped
cap_add:
- IPC_LOCK
ports:
- "8200:8200"
volumes:
- ./config:/openbao/config
- bao_data:/openbao/file
- bao_logs:/openbao/logs
environment:
BAO_LOG_LEVEL: ${BAO_LOG_LEVEL:-info}
BAO_ADDR: http://127.0.0.1:8200
command: ["server", "-config=/openbao/config/config.hcl"]
depends_on:
postgres:
condition: service_healthy
volumes:
postgres_data:
bao_data:
bao_logs:cap_add: IPC_LOCK ist Pflicht, damit OpenBao Secrets im RAM sperrt und nicht in den Swap auslagert. command: ["server", "-config=..."] verhindert den Dev-Modus des Images, in dem alle Daten nur im RAM liegen. BAO_ADDR sagt dem bao-Befehl im Container, dass der Listener ohne TLS läuft. Ohne die Variable meldet jeder bao-Aufruf „server gave HTTP response to HTTPS client“. Beim Start erscheint außerdem die harmlose Warnung „ignoring duplicate configuration“.
$ cd /opt/openbao
$ docker compose up -d$ docker compose psBeide Services zeigen Up, postgres zusätzlich (healthy).
$ docker compose logs openbao --tail=20Das Log enthält core: security barrier not initialized, aber keine Fehler zu Port, Volume oder Datenbankverbindung. Die Health-API antwortet in diesem Stadium mit HTTP 501 (nicht initialisiert).
Schritt 5: OpenBao initialisieren und entsiegeln (Unseal)
Nach dem ersten Start ist OpenBao noch nicht initialisiert. Die Initialisierung erzeugt die fünf Unseal-Schlüssel und den Root-Token. Danach ist OpenBao im Zustand sealed (versiegelt) und antwortet mit HTTP 503, bis genug Schlüssel eingegeben sind.
$ docker compose exec openbao bao operator initDie Ausgabe enthält fünf Unseal Keys und einen Initial Root Token. Speichern Sie diese Werte sofort in einem Passwortmanager. Sie lassen sich nicht wiederherstellen, ohne die Schlüssel bleibt der Datenspeicher dauerhaft verschlüsselt.
Entsiegeln Sie OpenBao mit drei der fünf Schlüssel (Shamir-Verfahren). Führen Sie den Befehl dreimal aus und geben Sie jedes Mal einen anderen Schlüssel ein:
docker compose exec openbao bao operator unseal
# Erster Schlüssel eingeben (Unseal Progress: 1/3)
docker compose exec openbao bao operator unseal
# Zweiter Schlüssel (Unseal Progress: 2/3)
docker compose exec openbao bao operator unseal
# Dritter Schlüssel (Sealed: false)Nach jedem Neustart muss das Unseal wiederholt werden. Auto-Unseal per AWS KMS, Azure Key Vault oder HSM ist seit 2.7.0 nicht mehr eingebaut, sondern ein externes Plugin.
$ curl -s http://localhost:8200/v1/sys/health | python3 -m json.toolBei erfolgreichem Unseal zeigt die Ausgabe "sealed": false und "initialized": true (HTTP 200); HTTP 503 heißt versiegelt. Alternativ per CLI:
$ docker compose exec openbao bao statusSealed muss false zeigen.
Schritt 6: Ersten Login und Secret anlegen
Mit dem Root-Token legen Sie das erste Secret an. Richten Sie danach zügig Policies und Auth-Methoden ein und sperren Sie den Root-Token weg.
# Root-Token setzen (IHR_ROOT_TOKEN ersetzen)
export BAO_TOKEN=IHR_ROOT_TOKEN
# KV-Secrets-Engine aktivieren
docker compose exec -e BAO_TOKEN=$BAO_TOKEN openbao \
bao secrets enable -path=secret kv-v2
# Erstes Secret schreiben
docker compose exec -e BAO_TOKEN=$BAO_TOKEN openbao \
bao kv put secret/meine-app db_password="supersicher" api_key="abc123"
# Secret lesen
docker compose exec -e BAO_TOKEN=$BAO_TOKEN openbao \
bao kv get secret/meine-appDie gleiche Abfrage geht per REST-API mit curl, die Vault-Endpunkte sind kompatibel.
curl -s -H "X-Vault-Token: $BAO_TOKEN" \
http://localhost:8200/v1/secret/data/meine-app | python3 -m json.toolDie Ausgabe zeigt db_password und api_key mit den gesetzten Werten, per curl unter data.data. HTTP 403 bedeutet ungültiger Token, HTTP 404 einen Pfad, den es nicht gibt.
Schritt 7: Container aktualisieren
Passen Sie für ein Update das Image-Tag in der compose.yaml an und führen Sie aus:
$ cd /opt/openbao
$ docker compose pull
$ docker compose up -dDanach ist OpenBao wieder versiegelt: Entsiegeln Sie es erneut mit drei Schlüsseln. Neue Releases melden Sie z. B. mit Diun oder WUD.
$ docker compose ps
$ docker compose exec openbao bao versionDie Version muss dem Tag in der compose.yaml entsprechen.
Hinweis für Bestandsinstallationen vor 2.7: Version 2.7.0 hat das file-Storage-Backend entfernt, ein Server mit storage "file" startet danach nicht mehr (unknown storage type file). Migrieren Sie solche Installationen mit bao operator migrate auf PebbleDB, Raft oder PostgreSQL, solange Ihr Binary file noch als Quelle akzeptiert (laut Changelog bis vor 2.8.0). Die Auth-Methoden LDAP, Kerberos und RADIUS sowie die LDAP-Secrets-Engine stecken seit 2.7.0 nicht mehr im Binary, sondern im Projekt openbao-plugins. Mit PostgreSQL-Backend wie in dieser Anleitung läuft das Update von 2.5.4 auf 2.7.1 ohne Eingriff, gespeicherte Secrets sind nach dem Entsiegeln lesbar.
Troubleshooting / Typische Fehler
- HTTP 503 nach dem Start
OpenBao ist versiegelt, normal nach jedem Neustart. Lösung:
docker compose exec openbao bao operator unsealdreimal mit je einem anderen Schlüssel aufrufen.- „server gave HTTP response to HTTPS client“
BAO_ADDR: http://127.0.0.1:8200fehlt imenvironmentdercompose.yaml. Eintrag ergänzen und mitdocker compose up -dneu anlegen.- HTTP 501 (not initialized)
Die Initialisierung fehlt noch. Lösung:
docker compose exec openbao bao operator initausführen und die Ausgabe sofort sichern.- „failed to lock memory“ / IPC_LOCK-Warnung
cap_add: IPC_LOCKfehlt in dercompose.yaml. Eintrag ergänzen und den Stack neu starten.- „invalid dsn“ beim Datenbankstart
Das PostgreSQL-Passwort enthält Sonderzeichen (
@,/,?,#), die in derconnection_urlURL-kodiert werden müssen. Beispiel:@→%40.- „error creating core: failed to create storage“
PostgreSQL war noch nicht bereit, oder Benutzer und Passwort in
config.hclund.envweichen ab (Log: „password authentication failed“). Prüfen Sie beides und den Healthcheck, danndocker compose restart openbao.- „unknown storage type file“ nach dem Update
Die Konfiguration nutzt noch das in 2.7.0 entfernte File-Backend. Daten mit
bao operator migrateauf ein unterstütztes Backend umziehen (siehe Schritt 7).- „permission denied“ beim PebbleDB-Backend
Das Volume gehört nicht dem Container-Benutzer
openbao. Prüfen Sie die UID/GID mitdocker compose exec openbao idund passen Sie die Rechte an.- Alle Secrets weg nach Neustart
OpenBao lief im Dev-Modus, erkennbar daran, dass kein Unseal nötig war. Setzen Sie
command: ["server", "-config=/openbao/config/config.hcl"]in dercompose.yamlund setzen Sie den Stack neu auf.- Unseal-Schlüssel verloren
Ohne ausreichend Schlüssel gibt es keine Wiederherstellung, nur den Neustart mit leerem Volume. Vorsorge: Schlüssel auf mehrere Personen verteilen oder Auto-Unseal einrichten.
Häufige Fragen
Wie unterscheidet sich OpenBao von HashiCorp Vault?
OpenBao ist ein Fork von Vault und wird seit dem BSL-Lizenzwechsel 2023 unter MPL-2.0 weiterentwickelt. API, CLI-Syntax und Konfigurationsformat sind weitgehend identisch. Der Befehl heißt bao statt vault, Umgebungsvariablen beginnen mit BAO_ statt VAULT_.
Muss ich OpenBao nach jedem Neustart manuell entsiegeln?
Mit dem Shamir-Seal ja: Nach jedem Neustart geben Sie drei der fünf Schlüssel ein. Auto-Unseal per AWS KMS, Azure Key Vault, GCP KMS oder HSM (PKCS#11) öffnet OpenBao beim Start automatisch. Seit 2.7.0 sind diese Seals externe Plugins, die Sie zusätzlich installieren.
Kann ich OpenBao ohne PostgreSQL betreiben?
Ja, mit dem PebbleDB-Backend (storage "pebbledb" { path = "/openbao/file" }). Es ersetzt das in 2.7.0 entfernte File-Backend, bietet aber keine Hochverfügbarkeit. Dafür eignen sich Raft oder PostgreSQL.
Gibt es eine Web-Oberfläche für OpenBao?
Ja. Setzen Sie ui = true in der config.hcl, danach antwortet http://SERVER:8200/ui/. Die UI ist seit 2.2.0 Teil des offiziellen Images.
Welche Ports müssen in der Firewall freigegeben werden?
Für einen Einzelknoten genügt 8200/TCP. Port 8201/TCP dient nur der Cluster-Kommunikation. Hinter einem Reverse Proxy geben Sie nur dessen Port 443 frei. Wie Sie die Firewall auf dem Host einrichten, zeigt Linux-Server absichern: UFW-Firewall und Fail2ban.
Wie sichere ich die OpenBao-Daten?
Die Daten liegen in der PostgreSQL-Datenbank (Volume postgres_data), bei PebbleDB im Volume bao_data. Sichern Sie PostgreSQL mit pg_dump und kopieren Sie die Dumps extern, siehe PostgreSQL-Backup mit cron und rclone. Bewahren Sie die Unseal-Schlüssel und den Root-Token getrennt von den Datensicherungen auf.
Ist OpenBao für den produktiven Einsatz geeignet?
Ja, die OpenBao-Dokumentation stuft das PostgreSQL-Backend als „production ready“ ein. Für Produktion brauchen Sie TLS (oder einen vorgelagerten Reverse Proxy mit HTTPS), Auto-Unseal und regelmäßige Backups. Einen Reverse Proxy mit HTTPS richten Sie mit Traefik als Docker-Reverse-Proxy ein.
Fazit
OpenBao ist ein API-kompatibler Vault-Fork unter MPL-2.0 ohne Lizenzrisiko. Per Docker Compose ist der Stack in rund 25 Minuten eingerichtet, das PostgreSQL-Backend taugt für Produktion. Operativ entscheidend ist der Unseal-Prozess: Unseal-Schlüssel und Root-Token sind nicht wiederherstellbar und gehören von Anfang an in sichere Verwahrung. Planen Sie für automatisierten Betrieb Auto-Unseal ein und sichern Sie die PostgreSQL-Daten regelmäßig.
Weiterführende Anleitungen und Quellen
- Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only für den Produktivbetrieb
- Vaultwarden produktiv betreiben: Argon2-Admin-Token, Fail2Ban und sicheres Backup
- Traefik als Docker-Reverse-Proxy mit automatischem HTTPS
- PostgreSQL-Backup automatisieren mit cron und rclone
- Single Sign-On für den Self-Hosted-Stack: Authentik vs. Authelia mit Traefik Forward-Auth
Offizielle Quellen: OpenBao Installationsdokumentation · GitHub-Repository · Docker Hub Image


