VaultWarden Passwort Manager

Vaultwarden Server-Dokumentation

Die Vaultwarden-Instanz läuft in einem Proxmox-Container und wird dort über Docker Compose betrieben. Die zentrale Arbeits- und Konfigurationsbasis liegt unter:

/opt/vaultwarden

Überblick

Vaultwarden ist eine selbst gehostete, Bitwarden-kompatible Passwortverwaltung. Die Anwendung läuft als Docker-Container und speichert ihre persistenten Daten lokal im Datenverzeichnis des Hosts.

Wichtige Punkte:

• Vaultwarden wird über Docker Compose gestartet und gestoppt.
• Die Konfiguration liegt im Verzeichnis /opt/vaultwarden.
• Die eigentlichen Vaultwarden-Daten liegen im Unterverzeichnis data.
• Änderungen an Domain, SMTP, Admin-Token oder weiteren Umgebungsvariablen erfolgen in der Docker-Compose-Konfiguration.
• Vor Änderungen an Konfiguration oder Datenbestand sollte immer ein Backup erstellt werden.

Serverzugriff

Der Zugriff auf den Server erfolgt per SSH.

Beispiel:

ssh root@SERVERNAME_ODER_IP

Nach dem Login in das Vaultwarden-Verzeichnis wechseln:

cd /opt/vaultwarden

Alle Docker-Compose-Befehle sollten aus diesem Verzeichnis heraus ausgeführt werden.

Verzeichnisstruktur

Die relevante Struktur sieht typischerweise so aus:

/opt/vaultwarden/
├── compose.yaml
├── compose.yaml.caddy        # optional / alte Variante mit Caddy
├── Caddyfile                 # optional, falls Caddy als Reverse Proxy genutzt wird/wurde
└── data/
    ├── db.sqlite3
    ├── db.sqlite3-shm
    ├── db.sqlite3-wal
    ├── attachments/
    ├── sends/
    ├── icon_cache/
    └── rsa_key.*

Die wichtigsten Dateien und Verzeichnisse:

Pfad	Bedeutung
/opt/vaultwarden/compose.yaml	Zentrale Docker-Compose-Konfiguration. Hier werden Container, Ports, Volumes und Umgebungsvariablen definiert.
/opt/vaultwarden/data	Persistente Vaultwarden-Daten. Dieses Verzeichnis ist besonders wichtig und muss gesichert werden.
/opt/vaultwarden/data/db.sqlite3	SQLite-Datenbank von Vaultwarden, sofern SQLite verwendet wird.
/opt/vaultwarden/Caddyfile	Reverse-Proxy-Konfiguration, falls Caddy genutzt wird oder genutzt wurde.
/opt/vaultwarden/compose.yaml.caddy	Gesicherte/alte Compose-Variante mit Caddy. Nur verwenden, wenn bewusst wieder auf diese Variante umgestellt werden soll.

Containerstatus prüfen

Im Verzeichnis /opt/vaultwarden:

docker compose ps

Alternativ alle laufenden Container anzeigen:

docker ps

Auch gestoppte Container anzeigen:

docker ps -a

Vaultwarden starten

cd /opt/vaultwarden
docker compose up -d

Danach prüfen, ob der Container läuft:

docker compose ps

Vaultwarden stoppen

cd /opt/vaultwarden
docker compose down

Der Befehl stoppt und entfernt den Container, löscht aber nicht die persistenten Daten im Verzeichnis data.

Vaultwarden neu starten

cd /opt/vaultwarden
docker compose restart

Alternativ vollständig stoppen und neu starten:

cd /opt/vaultwarden
docker compose down
docker compose up -d

Autostart

Vaultwarden wird über Docker Compose betrieben. Damit der Container nach einem Neustart des Servers automatisch wieder startet, sollte in der Datei /opt/vaultwarden/compose.yaml beim Vaultwarden-Service eine Restart-Policy gesetzt sein:

services:
  vaultwarden:
    restart: unless-stopped

Die Einstellung unless-stopped sorgt dafür, dass Vaultwarden nach einem Server-Neustart, Docker-Neustart oder Container-Absturz automatisch wieder gestartet wird. Wird der Container bewusst manuell gestoppt, bleibt er gestoppt.

Nach einer Änderung an der Compose-Datei muss die Konfiguration neu angewendet werden:

cd /opt/vaultwarden
docker compose up -d

Die aktuell gesetzte Restart-Policy kann geprüft werden mit:

docker inspect vaultwarden --format '{{.HostConfig.RestartPolicy.Name}}'

Erwartete Ausgabe:

unless-stopped

Zusätzlich muss Docker selbst beim Systemstart aktiviert sein:

systemctl enable docker
systemctl is-enabled docker

Logs anzeigen

Aktuelle Logs anzeigen:

docker logs vaultwarden

Live-Logs verfolgen:

docker logs -f vaultwarden

Wenn der Containername abweicht, vorher den Namen prüfen:

docker ps -a

Konfiguration bearbeiten

Die wichtigste Konfigurationsdatei ist:

/opt/vaultwarden/compose.yaml

Bearbeiten:

cd /opt/vaultwarden
vi compose.yaml

Nach Änderungen sollte die Konfiguration neu angewendet werden:

docker compose down
docker compose up -d

Danach Logs prüfen:

docker logs vaultwarden

Domain ändern

Wenn der Server unter einer anderen Domain erreichbar sein soll, muss die Domain in der Vaultwarden-Konfiguration angepasst werden.

Typischer Eintrag in compose.yaml:

environment:
  DOMAIN: "https://vault.example.org"

Die Domain muss zur späteren öffentlichen Adresse passen. Sie wird unter anderem für Links in E-Mails und für bestimmte Web-Vault-Funktionen verwendet.

Nach der Änderung:

cd /opt/vaultwarden
docker compose down
docker compose up -d

Danach prüfen:

docker logs vaultwarden

Zusätzlich muss geprüft werden, ob DNS, Reverse Proxy und Zertifikat ebenfalls auf die neue Domain zeigen.

Ports und Reverse Proxy

Vaultwarden läuft intern im Docker-Container. Die Erreichbarkeit von außen hängt von der Portfreigabe in compose.yaml und gegebenenfalls von einem Reverse Proxy ab.

Typische Varianten:

• Direkte Portfreigabe vom Container auf den Host.
• Reverse Proxy über Caddy, Nginx, Apache oder Proxmox-seitige Weiterleitung.
• TLS/HTTPS über vorgeschalteten Reverse Proxy.

Falls Vaultwarden nicht erreichbar ist, folgende Punkte prüfen:

cd /opt/vaultwarden
docker compose ps
docker ps
docker logs vaultwarden

Zusätzlich prüfen:

ss -tulpen

Damit lässt sich sehen, welche Dienste auf welchen Ports lauschen.

SMTP / E-Mail-Versand

Vaultwarden kann Einladungen, Passwort-Hinweise, Verifizierungen und weitere Benachrichtigungen per E-Mail versenden. Dafür müssen SMTP-Parameter in der Umgebungskonfiguration gesetzt sein.

Typische Einträge in compose.yaml:

environment:
  SMTP_HOST: "smtp.example.org"
  SMTP_FROM: "vaultwarden@example.org"
  SMTP_FROM_NAME: "Vaultwarden"
  SMTP_PORT: "587"
  SMTP_SECURITY: "starttls"
  SMTP_USERNAME: "vaultwarden@example.org"
  SMTP_PASSWORD: "PASSWORT_ODER_APP_PASSWORT"

Nach Änderungen:

cd /opt/vaultwarden
docker compose down
docker compose up -d
docker logs vaultwarden

Wenn SMTP nicht funktioniert, sind häufig folgende Punkte die Ursache:

• Falscher SMTP-Host.
• Falscher Port.
• Falsche Verschlüsselungsart, z. B. starttls vs. TLS auf Port 465.
• Falscher Benutzername oder falsches Passwort.
• SMTP-Anbieter blockiert den Login ohne App-Passwort.
• Firewall oder Provider blockiert ausgehende SMTP-Verbindungen.
• DOMAIN ist falsch gesetzt, dadurch zeigen Einladungslinks auf eine falsche Adresse.

Zum Testen nach dem Start zuerst die Logs prüfen:

docker logs vaultwarden

Benutzer und Einladungen

Benutzerverwaltung erfolgt entweder über die Vaultwarden-Weboberfläche oder über den Adminbereich, sofern dieser aktiviert ist.

Wichtig:

• Master-Passwörter von Benutzern können nicht einfach durch den Server-Administrator gesetzt oder ausgelesen werden.
• Wenn E-Mail-Versand aktiv, aber falsch konfiguriert ist, können Einladungen hängen bleiben.
• Wenn SMTP bewusst nicht verwendet wird, muss die Benutzeranlage entsprechend ohne E-Mail-Fluss geplant werden.
• Organisationsrollen wie Owner/Admin/User werden in der Organisation verwaltet.

Für neue Benutzer sollte bevorzugt der reguläre Einladungs- und Registrierungsprozess genutzt werden.

Adminbereich

Vaultwarden kann einen eigenen Adminbereich bereitstellen. Dieser ist üblicherweise erreichbar unter:

https://vault.example.org/admin

Der Zugriff wird über einen Admin-Token abgesichert, der in der Compose-Konfiguration als Umgebungsvariable gesetzt wird.

Typischer Eintrag:

environment:
  ADMIN_TOKEN: "SEHR_LANGER_ZUFALLSWERT"

Ein neuer Token kann zum Beispiel so erzeugt werden:

openssl rand -base64 48

Hinweise:

• Der Admin-Token darf nicht öffentlich dokumentiert werden.
• Der Token gehört nicht in eine allgemein zugängliche Wiki-Seite.
• Bei Weitergabe des Servers sollte geprüft werden, ob der Admin-Token geändert werden muss.
• Nach Änderung des Tokens muss Vaultwarden neu gestartet werden.

Backup

Das wichtigste Verzeichnis für Backups ist:

/opt/vaultwarden/data

Vor einem Backup sollte Vaultwarden gestoppt werden, damit die SQLite-Datenbank konsistent gesichert wird:

cd /opt/vaultwarden
docker compose down

tar -czf /root/vaultwarden-backup-$(date +%F).tar.gz /opt/vaultwarden

docker compose up -d

Danach prüfen:

docker compose ps
docker logs vaultwarden

Das Backup sollte sicher und getrennt vom Server gespeichert werden. Da Vaultwarden Passwortdaten enthält, muss das Backup entsprechend geschützt werden.

Restore

Für eine Wiederherstellung wird das gesicherte Verzeichnis zurückkopiert.

Beispiel:

cd /
tar -xzf /root/vaultwarden-backup-DATUM.tar.gz
cd /opt/vaultwarden
docker compose up -d

Danach prüfen:

docker compose ps
docker logs vaultwarden

Vor einem Restore sollte der aktuelle Stand gesichert oder umbenannt werden, damit keine Daten versehentlich überschrieben werden.

Update von Vaultwarden

Vor einem Update immer ein Backup erstellen.

Danach kann das neue Image gezogen und der Container neu gestartet werden:

cd /opt/vaultwarden

docker compose down
# optional: Backup erstellen

docker compose pull
docker compose up -d

Logs prüfen:

docker logs vaultwarden

Wenn nach einem Update Probleme auftreten, sollte zuerst die Compose-Konfiguration, die Logs und der Stand des Images geprüft werden.

Wichtige Standardbefehle

Zweck	Befehl
In das Projektverzeichnis wechseln	cd /opt/vaultwarden
Container starten	docker compose up -d
Container stoppen	docker compose down
Container neu starten	docker compose restart
Status anzeigen	docker compose ps
Logs anzeigen	docker logs vaultwarden
Live-Logs anzeigen	docker logs -f vaultwarden
Compose-Datei bearbeiten	vi /opt/vaultwarden/compose.yaml
Neues Image ziehen	docker compose pull
Backup erstellen	tar -czf /root/vaultwarden-backup-$(date +%F).tar.gz /opt/vaultwarden