Passbolt Community Edition ist ein Open-Source-Passwortmanager für Teams mit PGP-basierter Ende-zu-Ende-Verschlüsselung: Der private Schlüssel jedes Nutzers bleibt im Browser, der Server speichert nur verschlüsselte Daten. Passbolt bietet Freigaben mit Rechten (lesen, ändern, Eigentümer), Gruppen, MFA (TOTP), eine Browser-Extension für Chrome, Firefox, Edge und Brave sowie eine REST-API. Diese Anleitung zeigt, wie Sie Passbolt CE mit Docker Compose auf einem Linux-Host betreiben.

Voraussetzungen

Docker Engine >= 20.10 und Docker Compose v2 (Plugin oder Standalone) auf einem Linux-Host, einer VM oder einem NAS mit Docker-Unterstützung, siehe Docker und Docker Compose auf Linux installieren
Mindestens 1 GB RAM (empfohlen: 2 GB), 2 vCPUs, 10 GB freier Speicherplatz
Eigene Domain oder DNS-Eintrag für APP_FULL_BASE_URL; ohne passende URL verweigert die Browser-Extension die Verbindung
SMTP-Server oder SMTP-Relay (eigener Postfix oder das Relay Ihres Mail-Anbieters); ohne SMTP können Sie keine Nutzer einladen
SSL-Zertifikat: Passbolt besteht auf HTTPS. Für Produktion empfiehlt sich ein Reverse Proxy (Traefik oder Nginx) mit Let's Encrypt; für Tests ist ein self-signed Zertifikat möglich
Passbolt Browser-Extension (Chrome, Firefox, Edge oder Brave); ohne Extension ist kein Login möglich
openssl auf dem Host für Zufallswerte

Eckdaten auf einen Blick

Eigenschaft	Wert
Image (App)	`passbolt/passbolt:5.16.0-1-ce`
Image (DB)	`mariadb:10.11`
Ports	80 (HTTP→HTTPS-Redirect), 443 (HTTPS/UI/API)
Architektur	linux/amd64, linux/arm64
Volumes (Pflicht)	`database_volume`, `gpg_volume`, `jwt_volume`
Lizenz	AGPL v3, kostenlos (CE)
Einrichtungszeit	ca. 30 Minuten

Schritt 1: Projektordner und Verzeichnisstruktur anlegen

Erstellen Sie einen eigenen Ordner für den Passbolt-Stack. Alle weiteren Dateien liegen dort:

mkdir -p /opt/passbolt
cd /opt/passbolt

Optional, wenn Sie ein eigenes SSL-Zertifikat einbinden möchten:

mkdir -p /opt/passbolt/certs

Verifizieren: ls /opt/passbolt zeigt einen leeren Ordner oder nur certs/.

Schritt 2: .env-Datei mit Secrets anlegen

Alle sensiblen Werte kommen in eine .env-Datei, die nicht in ein Git-Repository gehört. Erzeugen Sie den SECURITY_SALT einmal zufällig und ändern Sie ihn danach nicht mehr: CakePHP nutzt ihn als Schlüssel für Hashes und Verschlüsselung, eine Änderung macht Sitzungen und damit gesicherte Daten ungültig.

Erzeugen Sie zunächst Zufallswerte:

# Sicheres Datenbankpasswort (32 Bytes, Base64)
openssl rand -base64 32

# Security Salt für CakePHP (mindestens 32 Zeichen)
openssl rand -base64 32

Legen Sie dann die .env-Datei an und tragen Sie die erzeugten Werte ein:

# /opt/passbolt/.env
# Datenbankpasswort (für MariaDB und Passbolt-App identisch!)
DB_PASSWORD=HIER_ZUFALLSPASSWORT_EINTRAGEN

# Vollständige URL inkl. https://, KEIN trailing slash
APP_FULL_BASE_URL=https://passbolt.example.com

# SMTP-Konfiguration (ohne SMTP können keine Nutzer eingeladen werden)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=user@example.com
SMTP_PASSWORD=SMTP_PASSWORT_HIER
EMAIL_FROM=no-reply@example.com

# Security Salt: EINMAL setzen, NIE mehr ändern!
SECURITY_SALT=HIER_ZUFALLS_SALT_EINTRAGEN

Schränken Sie die Dateirechte ein, damit andere Benutzer die Datei nicht lesen können:

chmod 600 /opt/passbolt/.env

Verifizieren: ls -la /opt/passbolt/.env zeigt Rechte -rw-------. Die Werte stehen ohne Anführungszeichen hinter dem Gleichheitszeichen.

Schritt 3: compose.yaml erstellen

Legen Sie die Compose-Datei /opt/passbolt/compose.yaml an. Der Stack besteht aus zwei Services: MariaDB und der Passbolt-App. Das mitgelieferte Skript wait-for.sh startet Passbolt erst, wenn die Datenbank auf Port 3306 erreichbar ist. Ein fester Versions-Tag statt latest-ce hält Updates planbar:

services:
  db:
    image: mariadb:10.11
    restart: unless-stopped
    environment:
      MYSQL_RANDOM_ROOT_PASSWORD: "true"
      MYSQL_DATABASE: "passbolt"
      MYSQL_USER: "passbolt"
      MYSQL_PASSWORD: "${DB_PASSWORD}"
    volumes:
      - database_volume:/var/lib/mysql

  passbolt:
    image: passbolt/passbolt:5.16.0-1-ce
    # Rootless-Variante (Ports im Container dann 8080/4433):
    # image: passbolt/passbolt:5.16.0-1-ce-non-root
    restart: unless-stopped
    depends_on:
      - db
    environment:
      APP_FULL_BASE_URL: "${APP_FULL_BASE_URL:-https://passbolt.local}"
      DATASOURCES_DEFAULT_HOST: "db"
      DATASOURCES_DEFAULT_USERNAME: "passbolt"
      DATASOURCES_DEFAULT_PASSWORD: "${DB_PASSWORD}"
      DATASOURCES_DEFAULT_DATABASE: "passbolt"
      EMAIL_TRANSPORT_DEFAULT_HOST: "${SMTP_HOST}"
      EMAIL_TRANSPORT_DEFAULT_PORT: "${SMTP_PORT:-587}"
      EMAIL_TRANSPORT_DEFAULT_USERNAME: "${SMTP_USER}"
      EMAIL_TRANSPORT_DEFAULT_PASSWORD: "${SMTP_PASSWORD}"
      EMAIL_TRANSPORT_DEFAULT_TLS: "true"
      EMAIL_DEFAULT_FROM: "${EMAIL_FROM}"
      EMAIL_DEFAULT_FROM_NAME: "Passbolt"
      SECURITY_SALT: "${SECURITY_SALT}"
      PASSBOLT_SSL_FORCE: "true"
      PASSBOLT_PLUGINS_SELF_REGISTRATION_ENABLED: "false"
      DEBUG: "false"
    volumes:
      - gpg_volume:/etc/passbolt/gpg
      - jwt_volume:/etc/passbolt/jwt
      # Eigenes SSL-Zertifikat (optional, sonst self-signed):
      # - ./certs/certificate.crt:/etc/passbolt/certs/certificate.crt:ro
      # - ./certs/certificate.key:/etc/passbolt/certs/certificate.key:ro
    command:
      [
        "/usr/bin/wait-for.sh",
        "-t",
        "0",
        "db:3306",
        "--",
        "/docker-entrypoint.sh",
      ]
    ports:
      # Hinter einem Reverse Proxy auf demselben Host nur lokal binden:
      # - "127.0.0.1:8443:443"
      - "80:80"
      - "443:443"
      # Für non-root-Image stattdessen:
      # - "80:8080"
      # - "443:4433"

volumes:
  database_volume:
  gpg_volume:
  jwt_volume:

PASSBOLT_PLUGINS_SELF_REGISTRATION_ENABLED: "false" verhindert Selbstregistrierung; nur eingeladene Nutzer erhalten Zugang. Die Ports 80 und 443 sind öffentlich erreichbar, Passbolt liefert auf 443 selbst HTTPS aus. Betreiben Sie einen Reverse Proxy, binden Sie Passbolt nur an 127.0.0.1 (Kommentarzeile oben).

Verifizieren: docker compose -f /opt/passbolt/compose.yaml config meldet keinen Syntaxfehler und zeigt statt ${VAR}-Platzhaltern die Werte aus der .env-Datei.

Schritt 4: Stack starten

Starten Sie den Stack im Projektordner:

cd /opt/passbolt
docker compose up -d

Beim ersten Start initialisiert MariaDB Datenbank und Benutzer; Passbolt wartet auf Port 3306, legt das Datenbankschema an und erzeugt GPG-Serverschlüssel und JWT-Keys. Das dauert etwa 60 bis 90 Sekunden.

Verfolgen Sie den Startvorgang:

docker compose logs -f passbolt

Beenden Sie den Log-Stream mit Strg+C, sobald keine neuen Zeilen mehr erscheinen und kein ERROR sichtbar ist.

Verifizieren:

docker compose ps

Erwartete Ausgabe (beide Container Up, kein Restarting):

NAME                IMAGE                           STATUS
passbolt-db-1       mariadb:10.11                   Up X minutes
passbolt-passbolt-1 passbolt/passbolt:5.16.0-1-ce   Up X minutes

Prüfen Sie zusätzlich den Status-Endpunkt (-k übergeht ein self-signed Zertifikat):

curl -sk https://localhost/healthcheck/status.json

Erwartete Antwort: JSON mit "status":"success" und "body":"OK".

Schritt 5: Ersten Admin-Benutzer anlegen

Im Docker-Image legen Sie den ersten Admin per CLI-Befehl im laufenden Container an. Führen Sie den Befehl als Benutzer www-data aus, sonst entstehen falsche Dateirechte in den GPG-Verzeichnissen:

docker compose exec passbolt su -m -c \
  'bin/cake passbolt register_user \
  -u admin@example.com \
  -f Vorname \
  -l Nachname \
  -r admin' \
  -s /bin/sh www-data

Ersetzen Sie admin@example.com, Vorname und Nachname durch echte Werte. Der Befehl gibt eine Einladungs-URL aus, zum Beispiel:

The user has been registered successfully.
To complete the setup, follow the link provided below.
https://passbolt.example.com/setup/install/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Installieren Sie die Browser-Extension aus dem jeweiligen Store (Chrome Web Store, Firefox Add-ons, Microsoft Edge Add-ons) und öffnen Sie dann diese URL. Der Einrichtungsassistent erzeugt Ihr persönliches PGP-Schlüsselpaar und bietet das Wiederherstellungskit mit dem privaten Schlüssel zum Download an. Bewahren Sie es sicher auf: Ohne privaten Schlüssel lassen sich Ihre Passwörter nicht entschlüsseln.

Verifizieren: Nach Abschluss des Assistenten melden Sie sich unter https://passbolt.example.com an. Unter Benutzer erscheinen Sie als einziger Nutzer mit der Rolle „Admin“.

Schritt 6: SMTP testen und weitere Nutzer einladen

Prüfen Sie vor der ersten Einladung den SMTP-Versand; sonst erhalten Nutzer keine Aktivierungs-E-Mail, ohne dass ein Fehler erscheint:

docker compose exec passbolt su -m -c \
  'bin/cake passbolt send_test_email \
  --recipient=ihre@email.de' \
  -s /bin/sh www-data

Weitere Nutzer laden Sie in der Weboberfläche unter Benutzer → Neuer Benutzer ein. Passbolt sendet eine E-Mail mit Setup-Link; jeder Nutzer installiert die Browser-Extension und erzeugt beim ersten Login sein eigenes Schlüsselpaar.

Mit Gruppen teilen Sie Passwörter mit mehreren Nutzern auf einmal, jeweils mit den Rechten lesen, ändern oder Eigentümer.

Verifizieren: Der Test-E-Mail-Befehl gibt The email was sent successfully. aus. Im Posteingang der Empfänger-Adresse erscheint eine Test-E-Mail von Passbolt. Neue Nutzer erhalten nach der Einladung eine E-Mail mit Aktivierungslink.

Schritt 7: Vollständigen Healthcheck ausführen

Der integrierte Diagnosebefehl prüft Datenbankverbindung, GPG-Konfiguration, SSL und weitere Komponenten:

docker compose exec passbolt su -m -c \
  'bin/cake passbolt healthcheck' \
  -s /bin/sh www-data

Verifizieren: Die Ausgabe endet ohne [FAIL]-Zeilen. Mit self-signed Zertifikat meldet der SSL-Abschnitt eine fehlgeschlagene Zertifikatsprüfung; das ist im Testbetrieb erwartet und verschwindet mit einem gültigen Zertifikat.

Schritt 8: Updates und Backups

Das allgemeine 3-2-1-Prinzip beschreibt 3-2-1-Backup-Strategie umsetzen. Für Passbolt sichern Sie mindestens die Datenbank und das gpg_volume: Ohne den GPG-Serverschlüssel können sich die Nutzer an einer wiederhergestellten Instanz nicht mehr anmelden. Die Passwörter selbst sind mit den Schlüsseln der Nutzer verschlüsselt; deshalb braucht jeder Nutzer zusätzlich sein Wiederherstellungskit.

Datenbank sichern:

cd /opt/passbolt
docker compose exec -T db sh -c 'mariadb-dump -u passbolt -p"$MYSQL_PASSWORD" passbolt' \
  > /opt/passbolt/backup_$(date +%Y%m%d).sql

Die einfachen Anführungszeichen sorgen dafür, dass $MYSQL_PASSWORD im Container aufgelöst wird; -T verhindert Steuerzeichen im Dump.

GPG-Volume sichern:

docker run --rm \
  -v passbolt_gpg_volume:/data \
  -v /opt/passbolt:/backup \
  alpine tar czf /backup/gpg_backup_$(date +%Y%m%d).tar.gz /data

Update: Setzen Sie den Image-Tag in compose.yaml auf die neue Version und führen Sie aus:

cd /opt/passbolt
docker compose pull
docker compose up -d

Passbolt führt Datenbankmigrationen beim Start automatisch aus. Erstellen Sie vor jedem Update ein Backup und führen Sie nie docker compose down -v aus: -v löscht die Named Volumes.

Verifizieren: ls -l /opt/passbolt/backup_*.sql /opt/passbolt/gpg_backup_*.tar.gz zeigt zwei Dateien größer als 0 Byte. Nach einem Update zeigen docker compose ps beide Container als Up und curl -sk https://localhost/healthcheck/status.json liefert "body":"OK".

Troubleshooting / Typische Fehler

„SQLSTATE[HY000] [1045] Access denied“ in docker compose logs passbolt: Das Datenbankpasswort in MYSQL_PASSWORD (db-Service) stimmt nicht mit DATASOURCES_DEFAULT_PASSWORD (passbolt-Service) überein. Beide Services lesen ${DB_PASSWORD} aus der .env-Datei. Wurde das Passwort nach dem ersten Start geändert, gilt in MariaDB weiter das alte: Setzen Sie den alten Wert zurück oder ändern Sie das Passwort in der Datenbank.
Container startet in Restart-Loop: Häufigste Ursache ist ein noch nicht bereiter Datenbankserver. In den Logs auf waiting for db:3306 achten. Normalerweise fängt wait-for.sh das ab; sonst hilft docker compose restart passbolt nach 30 Sekunden.
Browser-Extension meldet abweichende Domain: APP_FULL_BASE_URL stimmt nicht exakt mit der URL im Browser überein. Die URL muss https:// enthalten, darf keinen abschließenden Schrägstrich haben und muss DNS-auflösbar sein. Für lokale Tests /etc/hosts anpassen: 127.0.0.1 passbolt.local.
SMTP-Test schlägt fehl / Nutzer erhalten keine E-Mail: SMTP_HOST, SMTP_PORT und Zugangsdaten prüfen. Für Port 587 muss EMAIL_TRANSPORT_DEFAULT_TLS=true gesetzt sein. Der Test-Befehl aus Schritt 6 zeigt die SMTP-Fehlermeldung direkt.
register_user-Befehl schlägt mit Permission-Fehler fehl: Der Befehl wurde nicht als www-data ausgeführt. Verwenden Sie immer su -m -c '...' -s /bin/sh www-data, nie direkt root.
SECURITY_SALT nachträglich geändert: Sitzungen und mit dem Salt verschlüsselte Einstellungen werden ungültig. Setzen Sie den ursprünglichen Wert aus der gesicherten .env zurück und starten Sie den Stack neu.
Browser warnt vor self-signed Zertifikat: Schalten Sie für den Produktivbetrieb einen Reverse Proxy mit Let's Encrypt vor oder legen Sie ein eigenes Zertifikat in ./certs/ ab und aktivieren Sie die auskommentierten Volume-Zeilen in compose.yaml.

Häufige Fragen

Können Sie Passbolt hinter einem Reverse Proxy (Traefik/Nginx) betreiben?

Ja, das ist der empfohlene Weg für die Produktion. Der Proxy übernimmt TLS und leitet an Passbolt weiter; binden Sie Passbolt dann nur an 127.0.0.1 und setzen Sie PASSBOLT_SECURITY_PROXIES_ACTIVE=true. APP_FULL_BASE_URL ist die öffentliche HTTPS-URL des Proxys. Wie Sie Traefik als Docker-Reverse-Proxy einrichten, erklärt die gleichnamige Anleitung.

Was ist der Unterschied zwischen CE und Pro?

Die Community Edition ist vollständig kostenlos, Open Source (AGPL v3) und enthält alle Kernfunktionen: unbegrenzte Nutzer, unbegrenzte Gruppen, MFA, Browser-Extension, REST-API und Import/Export. Die Pro-Edition ergänzt unter anderem Aktivitätsprotokoll (Audit-Log), LDAP/Active-Directory-Synchronisation, SSO und Herstellersupport.

Wie sichern Sie die Passbolt-Instanz gegen unbefugten Zugriff ab?

PASSBOLT_PLUGINS_SELF_REGISTRATION_ENABLED=false ist in der Compose-Vorlage gesetzt; nur eingeladene Nutzer erhalten ein Konto. Zusätzlich empfiehlt sich MFA für alle Nutzer (PASSBOLT_PLUGINS_MFA_PROVIDERS_TOTP=true), ein gehärteter Linux-Host und ein abgesichertes Compose-Setup, siehe Docker Compose absichern: Secrets, Healthchecks, Non-Root.

Welche Architekturen werden unterstützt?

Das offizielle Image gibt es für linux/amd64 und linux/arm64 (z. B. Raspberry Pi 4/5). ARMv7 (32-Bit) wird nicht offiziell unterstützt.

Wie nutzen Sie Docker Secrets statt Klartext-Passwörtern in der .env?

Der Einstiegspunkt des Images liest Datenbank- und SMTP-Zugangsdaten auch aus Dateien (Suffix _FILE). Statt DATASOURCES_DEFAULT_PASSWORD=geheim können Sie DATASOURCES_DEFAULT_PASSWORD_FILE=/run/secrets/db_password setzen und das Secret einbinden. Setzen Sie nie beide Varianten gleichzeitig, sonst bricht der Start ab.

Wie lesen Sie Logs bei Problemen?

Anwendungsfehler zeigt docker compose logs passbolt, Datenbankprobleme docker compose logs db. Eine vollständige Diagnose liefert der Healthcheck aus Schritt 7.

Fazit

Passbolt CE verschlüsselt Passwörter im Browser mit den Schlüsseln der Nutzer; der Server sieht keine Klartexte. Der Stack aus zwei Containern ist überschaubar. Planen Sie SMTP vor dem ersten Start ein, sichern Sie Datenbank und GPG-Serverschlüssel regelmäßig und lassen Sie jeden Nutzer sein Wiederherstellungskit aufbewahren.

Weiterführende Anleitungen und Quellen

Offizielle Quellen: Passbolt — Install on Docker (offizielle Dokumentation) | passbolt/passbolt_docker auf GitHub | Passbolt Environment Variables Reference | passbolt/passbolt auf Docker Hub