Homelab--Bratonein-Kontrollzentrum--Tutorial/Kapitel 5/Free Rohtext.md

# Kapitel 5 – Vaultwarden (Passwörter, 2FA)

## Einleitung

Zugangsdaten gehören zu den sensibelsten Informationen im digitalen Alltag.  
Ob Streaming-Tools, Creator-Plattformen, E-Mail-Konten, Domains oder Selfhosting-Dienste – jeder Dienst hat sein eigenes Passwort, manche erfordern zusätzlich Zwei-Faktor-Codes (2FA).  

### Das Problem mit Passwörtern im Alltag

Oft landen Passwörter:
- in Browsern, die ohne Hauptkennwort speichern,
- in Textdateien auf dem Desktop,
- oder werden für mehrere Konten wiederverwendet.

Zwei-Faktor-Codes liegen dann verstreut in Authenticator-Apps auf dem Handy – ohne Backup und nicht synchronisierbar.

> [!WARNING]  
> Wer 2FA-Codes verliert, verliert oft dauerhaft den Zugriff.  
> Viele Dienste bieten keinen Wiederherstellungsprozess ohne die Codes.

### Vaultwarden als Lösung

Vaultwarden ist ein selbst gehosteter Passwort-Manager.  
Er speichert Passwörter und 2FA-Codes verschlüsselt auf dem eigenen Server – vollständig kompatibel mit den offiziellen Bitwarden-Apps für Browser, Desktop und Mobilgeräte.

Der Zugriff erfolgt über eine zentrale Weboberfläche, erreichbar unter einer eigenen Domain wie `https://pass.DEINE-DOMAIN.tld`, mit gültigem SSL-Zertifikat und WebSocket-Sync.

> [!TIP]  
> Vaultwarden ist die leichtgewichtige, Docker-basierte Variante von Bitwarden – ohne Cloud, ohne Abo, ohne Datenweitergabe.

### Ziel dieses Kapitels

Wir richten Vaultwarden in einem eigenen Debian‑12‑LXC per Docker Compose ein und machen ihn per Nginx Proxy Manager erreichbar.  
Dabei setzen wir auf verschlüsselte Kommunikation (HTTPS), geschützte WebSocket-Verbindung und ein gehärtetes Admin-Backend mit Hash-Login.  

Am Ende des Kapitels steht ein voll einsatzfähiger Passwort-Manager:
- auf eigener Hardware,  
- mit geschlossener Registrierung,  
- sicher erreichbar von jedem Gerät.  

---

## Voraussetzungen & Ressourcen

Vaultwarden wird in einem eigenen LXC-Container unter Debian 12 betrieben.  
Ein LXC ist ein leichtgewichtiger Container unter Proxmox – ideal für einzelne Dienste wie diesen. Die Einrichtung haben wir bereits in Kapitel 1 Schritt für Schritt gezeigt.

### Anforderungen an den Container

- **Betriebssystem:** Debian 12  
- **CPU:** 1 Kern  
- **RAM:** 512 MB  
- **Festplatte:** 8 GB  
- **IP-Adresse:** 192.168.1.50 (per DHCP-Reservierung im Router fest zugewiesen)  
- **Internetverbindung:** erforderlich für Paketinstallation und Docker-Download

> [!TIP]  
> Vergib die IP-Adresse über eine **DHCP-Reservierung im Router**, nicht außerhalb des DHCP-Bereichs.  
> So stellst du sicher, dass die Adresse dauerhaft erhalten bleibt – ohne Konflikte mit anderen Geräten.

👉 *Screenshot geeignet: Proxmox – LXC erstellen → Allgemeine Einstellungen mit Hostname „vaultwarden“*

### Subdomain & Reverse Proxy

Damit Vaultwarden später über eine Webadresse erreichbar ist, benötigen wir:

- Eine Subdomain wie `pass.meinedomain.de`  
- Einen laufenden Nginx Proxy Manager (siehe Kapitel 3), der HTTPS-Anfragen an den Vaultwarden-Container weiterleiten kann

> [!NOTE]  
> Du kannst auch eine kostenlose DynDNS-Adresse verwenden – z. B. über DuckDNS.  
> Wichtig ist nur, dass der Proxy Manager Anfragen zuverlässig an die IP `192.168.1.50` weiterleitet.

👉 *Screenshot geeignet: DuckDNS-Dashboard mit Subdomain + NPM-Dashboard mit Proxy Host*

## Schritt-für-Schritt-Anleitung

### System vorbereiten

Wir starten im frisch erstellten LXC-Container.  
Öffne in Proxmox den Container `vaultwarden` und klicke im Menü auf **Konsole**.

Zuerst bringen wir das System auf den aktuellen Stand und installieren die benötigten Hilfspakete.  
Diese sorgen dafür, dass externe Paketquellen sicher eingebunden und später Docker korrekt installiert werden kann.

    apt update
    apt upgrade -y
    apt install -y ca-certificates curl gnupg lsb-release

> [!NOTE]  
> Diese Pakete ermöglichen verschlüsselte Verbindungen, das Verifizieren von Signaturen und das Erkennen der verwendeten Systemversion.

👉 *Screenshot geeignet: Proxmox-Konsole mit apt upgrade und Paketinstallation*

### Docker und Compose installieren

Vaultwarden wird als Docker-Anwendung betrieben.  
Dafür installieren wir die aktuelle Docker Engine und das dazugehörige Compose-Plugin direkt aus dem offiziellen Repository.

1. Verzeichnis für den Signaturschlüssel anlegen:

    mkdir -p /etc/apt/keyrings

2. Docker-Signaturschlüssel herunterladen und abspeichern:

    curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

3. Docker-Repository hinzufügen:

    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
    $(. /etc/os-release && echo $VERSION_CODENAME) stable" > /etc/apt/sources.list.d/docker.list

4. Paketlisten aktualisieren und Docker installieren:

    apt update
    apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

5. Docker beim Systemstart automatisch aktivieren:

    systemctl enable --now docker

> [!TIP]  
> Prüfe die Installation mit folgenden Befehlen:

    docker --version
    docker compose version

👉 *Screenshot geeignet: Terminalausgabe mit Docker- und Compose-Version*

> [!WARNING]  
> Falls Docker im Container nicht startet:  
> In Proxmox → Container auswählen → Reiter „Optionen“ → Haken bei „Nesting“ und „keyctl“ setzen → Container neu starten.

👉 *Screenshot geeignet: Proxmox → CT-Optionen mit aktivierten Haken*

### Projektstruktur & .env-Datei

Wir legen jetzt die Verzeichnisstruktur für Vaultwarden an und erstellen eine Konfigurationsdatei `.env`.  
Diese Datei enthält später wichtige Einstellungen wie die Adresse des Dienstes und (optional) SMTP-Daten für Mailversand.

Öffne die Konsole des Containers und gib folgende Befehle ein:

    mkdir -p /opt/vaultwarden/data
    cd /opt/vaultwarden
    nano .env

Es öffnet sich der Nano-Editor. Trage hier Folgendes ein:

    DOMAIN=https://pass.DEINE-DOMAIN.tld
    SIGNUPS_ALLOWED=false

    # Optional: SMTP für Verifizierung und Passwort-Reset
    # SMTP_HOST=smtp.example.com
    # SMTP_FROM=pass@example.com
    # SMTP_PORT=587
    # SMTP_SECURITY=starttls
    # SMTP_USERNAME=nutzername
    # SMTP_PASSWORD=deinSMTPpasswort

> [!TIP]  
> Trage die Domain unbedingt **mit https://** ein.  
> Ohne Protokollangabe können später Links in Mails oder der Weboberfläche fehlerhaft sein.

> [!NOTE]  
> Die Option `SIGNUPS_ALLOWED=false` deaktiviert die offene Registrierung.  
> Du aktivierst sie später kurzzeitig manuell, um deinen ersten Nutzer anzulegen.

Speichern mit:  
Strg + O → Enter → Strg + X

👉 *Screenshot geeignet: Nano-Editor mit ausgefüllter .env-Datei*

### docker-compose.yml erstellen

Vaultwarden wird über Docker Compose gestartet.  
Dazu legen wir eine Datei namens `docker-compose.yml` an, die beschreibt, welches Image verwendet wird, auf welchen Ports der Dienst erreichbar ist und wo die Daten gespeichert werden.

Gib in der Konsole ein:

    nano docker-compose.yml

Füge folgenden Inhalt ein:

    services:
      vaultwarden:
        image: vaultwarden/server:latest
        container_name: vaultwarden
        restart: unless-stopped
        env_file: .env
        environment:
          - DOMAIN=${DOMAIN}
        volumes:
          - ./data:/data
        ports:
          - "8000:80"
          - "3012:3012"

> [!NOTE]  
> Port 8000 wird später im Nginx Proxy Manager als Weiterleitungsziel eingetragen.  
> Port 3012 ist für WebSockets zuständig – ohne ihn funktioniert der Live-Sync zwischen Geräten nicht.

Speichern mit:  
Strg + O → Enter → Strg + X

👉 *Screenshot geeignet: docker-compose.yml im Nano-Editor mit vollständigem Inhalt*

### Container starten & Logs prüfen

Sobald alle Dateien angelegt sind, starten wir Vaultwarden zum ersten Mal.  
Dabei wird das Docker-Image heruntergeladen, der Container erstellt und im Hintergrund ausgeführt.

Gib in der Konsole ein:

    docker compose up -d

> [!TIP]  
> Der Parameter `-d` sorgt dafür, dass der Container im Hintergrund („detached“) läuft.

Prüfe danach, ob der Container fehlerfrei gestartet wurde:

    docker compose logs -f --tail=80 vaultwarden

Wenn alles korrekt eingerichtet ist, erscheint nach einigen Sekunden die Meldung:

    Rocket has launched from http://0.0.0.0:80

Das bedeutet, dass Vaultwarden intern erfolgreich auf Port 80 gestartet wurde.

> [!NOTE]  
> Wenn stattdessen Fehlermeldungen wie „permission denied“ oder „/data not writable“ auftauchen,  
> überprüfe die Rechte des Datenordners oder lösche einen fehlerhaften Container mit:

    docker compose down
    docker compose up -d

👉 *Screenshot geeignet: Terminal mit „Rocket has launched...“-Ausgabe im Log*

### Veröffentlichung im Nginx Proxy Manager

Vaultwarden läuft nun intern auf Port 8000 des Containers.  
Damit der Dienst auch von außen über eine Domain wie `https://pass.DEINE-DOMAIN.tld` erreichbar ist, richten wir ihn im Nginx Proxy Manager (NPM) als neuen Proxy Host ein.

Öffne die NPM-Weboberfläche:  
http://<IP-des-NPM-Containers>:81

> [!NOTE]  
> Die Einrichtung von NPM haben wir ausführlich in Kapitel 3 gezeigt.  
> Falls du dir nicht sicher bist, wie du einen Proxy Host anlegst, sieh dir das dortige Beispiel erneut an.

#### Proxy Host hinzufügen

1. Gehe auf **Hosts → Proxy Hosts**  
2. Klicke auf **Add Proxy Host**

Fülle die Felder wie folgt aus:

- **Domain Names:** `pass.DEINE-DOMAIN.tld`  
- **Scheme:** `http`  
- **Forward Hostname / IP:** `192.168.1.50`  
- **Forward Port:** `8000`  
- **Block Common Exploits:** aktivieren  
- **Websockets Support:** aktivieren

👉 *Screenshot geeignet: Proxy Host Maske mit IP 192.168.1.50 und Port 8000*

#### WebSocket-Weiterleitung hinzufügen

Vaultwarden nutzt WebSockets für den Live-Sync zwischen Geräten.  
Dafür muss eine spezielle Weiterleitung für den Pfad `/notifications/hub` eingerichtet werden.

1. Klicke im Proxy Host auf den Reiter **Custom Locations**  
2. Wähle **Add Location**

Trage ein:

- **Location:** `/notifications/hub`  
- **Forward Hostname / IP:** `192.168.1.50`  
- **Forward Port:** `3012`  
- **Websockets Support:** aktivieren

Speichern und zurück zum Hauptfenster des Proxy Hosts.

👉 *Screenshot geeignet: Custom Location mit WebSocket-Port 3012*

#### SSL-Zertifikat erstellen

Wechsle in den Reiter **SSL** und richte ein gültiges HTTPS-Zertifikat ein:

- **SSL Certificate:** Request a new SSL Certificate  
- **Force SSL:** aktivieren  
- **HTTP/2 Support:** aktivieren  
- **HSTS Enabled:** aktivieren  
- **Agree to terms:** Haken setzen

> [!TIP]  
> Achte darauf, dass die Domain bereits auf deinen Server zeigt.  
> Die Validierung von Let’s Encrypt funktioniert nur, wenn die Ports 80 und 443 korrekt weitergeleitet wurden.

Speichern. Der Proxy Host wird nun aktiv.  
Rufe im Browser `https://pass.DEINE-DOMAIN.tld` auf.  
Die Login-Seite von Vaultwarden sollte jetzt erscheinen.

👉 *Screenshot geeignet: Browseransicht mit Vaultwarden-Loginmaske unter HTTPS-Adresse*

### Admin-Absicherung & Benutzer anlegen

Vaultwarden besitzt ein separates Admin-Interface unter:  
`https://pass.DEINE-DOMAIN.tld/admin`

Beim ersten Aufruf erscheint ein Warnhinweis:  
Die Nutzung eines einfachen Admin-Tokens in Klartext ist unsicher.  
Stattdessen hinterlegen wir einen verschlüsselten Zugriffscode im Format **Argon2 PHC**.

#### Sicheren Admin-Token erzeugen

Vaultwarden enthält ein eingebautes Werkzeug zum Erzeugen dieses Hashes.

Gib in der Konsole des Containers ein:

    docker exec -it vaultwarden /vaultwarden hash --preset owasp

Du wirst zweimal nach dem gewünschten Admin-Passwort gefragt.  
Am Ende erscheint ein langer Code, der mit `$argon2id$` beginnt.  
Diesen **komplett kopieren** – er wird später im Adminbereich eingetragen.

> [!NOTE]  
> Dieser Code ist nicht das Passwort selbst, sondern ein sicherer Rechenwert daraus.  
> Du verwendest weiterhin das **eingegebene Passwort**, nicht den Hash zum Login.

👉 *Screenshot geeignet: Konsole mit Ausgabe des Argon2-Hashes*

#### Hash im Webinterface eintragen

1. Öffne `https://pass.DEINE-DOMAIN.tld/admin`  
2. Logge dich mit dem neuen Passwort ein  
3. Gehe zu **Settings → General**  
4. Trage den kopierten Hash in das Feld **Admin Token / Argon2 PHC** ein  
5. Speichern

Ab jetzt ist der Adminbereich mit dem sicheren Hash geschützt.  
Der alte Klartext-Eintrag darf entfernt werden.

> [!TIP]  
> Öffne die `.env`-Datei und lösche die Zeile mit `ADMIN_TOKEN=`  
> Danach den Container neu starten:

    sed -i '/^ADMIN_TOKEN=/d' /opt/vaultwarden/.env
    cd /opt/vaultwarden && docker compose restart vaultwarden

👉 *Screenshot geeignet: Adminbereich mit gespeichertem Hash + Login-Maske*

#### Ersten Benutzer anlegen

Vaultwarden lässt keine offenen Registrierungen zu – genau das haben wir in der `.env` vorher deaktiviert.  
Um den ersten Benutzer anzulegen, aktivieren wir die Anmeldung **kurzzeitig manuell**:

1. Adminbereich öffnen → **Settings → General**  
2. Option **Allow new signups** aktivieren → Speichern  
3. In einem zweiten Tab `https://pass.DEINE-DOMAIN.tld/#/register` öffnen  
4. Benutzer registrieren  
5. Danach Anmeldung testen und die Registrierung wieder deaktivieren

> [!TIP]  
> Alternativ kannst du Nutzer auch über **Users → Invitations** per E-Mail einladen, wenn SMTP korrekt konfiguriert ist.

👉 *Screenshot geeignet: Registrierung und späterer Login im Tresor*

### Backups & Wiederherstellung

Vaultwarden speichert alle Daten in einem lokalen Ordner – das betrifft sowohl Passwörter, Benutzer, Konfigurationen als auch Anhänge und TOTP-Codes.

Wichtig:  
Nicht der Docker-Container ist relevant, sondern der **Ordner `/opt/vaultwarden/data`**.  
Nur dieser Ordner muss regelmäßig gesichert werden.

#### Manuelles Backup erstellen

Ein manuelles Backup kannst du direkt im Container-Terminal erstellen:

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

> [!TIP]  
> Wenn du maximale Datensicherheit willst, kannst du Vaultwarden vor dem Backup kurz stoppen:

    docker compose stop vaultwarden

> [!NOTE]  
> Für kleine Setups ist ein Online-Backup im laufenden Betrieb meist ausreichend.

Nach dem Backup startest du den Container bei Bedarf wieder:

    docker compose start vaultwarden

Die Backup-Datei liegt danach unter `/root/` und heißt z. B. `vaultwarden-backup-2025-10-04.tar.gz`

👉 *Screenshot geeignet: Terminalausgabe nach erfolgreicher Archivierung*

#### Wiederherstellung

Falls du Vaultwarden auf einem neuen System wiederherstellen musst:

1. Neue Instanz bis zur `docker-compose.yml` einrichten  
2. Backup-Datei nach `/opt/vaultwarden/` kopieren  
3. Archiv entpacken:

    tar -xzf vaultwarden-backup-2025-10-04.tar.gz

4. Container starten:

    docker compose up -d

Das System ist danach wieder wie vorher nutzbar – inklusive aller Benutzer, Einstellungen und Daten.

> [!WARNING]  
> Stelle sicher, dass die Zugriffsrechte auf den Ordner `data` erhalten bleiben.  
> Andernfalls kann Vaultwarden die Datenbank nicht korrekt öffnen.

---

## Troubleshooting & Tipps

### Vaultwarden lädt nicht im Browser

Wenn sich die Seite `https://pass.DEINE-DOMAIN.tld` nicht öffnet:

- Öffne in Proxmox den Container `vaultwarden`  
- Klicke auf **Konsole**  
- Gib ein:

    docker compose ps

In der Spalte „State“ muss „running“ stehen.

Falls nicht, starte den Container erneut:

    docker compose up -d

👉 *Screenshot geeignet: Ausgabe von `docker compose ps` mit Status „running“*

> [!TIP]  
> Du kannst auch testen, ob Vaultwarden intern erreichbar ist:  
> Öffne `http://192.168.1.50:8000` im Browser.  
> Wenn dort die Login-Maske erscheint, funktioniert Vaultwarden – das Problem liegt am Proxy.

### Die Domain funktioniert, aber es erscheint keine Login-Maske

Öffne den Nginx Proxy Manager und gehe wie folgt vor:

- Klicke auf den Proxy Host für `pass.DEINE-DOMAIN.tld`  
- Prüfe:
  - IP-Adresse: `192.168.1.50`  
  - Port: `8000`  
  - Haken bei „Block Common Exploits“ und „Websockets Support“

👉 *Screenshot geeignet: Proxy Host Übersicht mit richtiger IP und Port*

- Wechsle in den Reiter **Custom Locations**  
- Prüfe:
  - Location: `/notifications/hub`  
  - Ziel-Port: `3012`  
  - WebSocket-Support: aktiviert

👉 *Screenshot geeignet: Custom Location mit aktivem Websocket-Haken*

> [!TIP]  
> Änderungen speichern, Proxy Host kurz deaktivieren und wieder aktivieren.

### Die Seite lädt, aber nichts funktioniert richtig

Wenn z. B. das Design fehlt oder Buttons nicht reagieren:

- Öffne die `.env`-Datei mit:

    nano /opt/vaultwarden/.env

- Prüfe, ob die Domain mit `https://` eingetragen ist:

    DOMAIN=https://pass.DEINE-DOMAIN.tld

Fehlt das `https://`, tragen wir es nach und starten neu:

    docker compose restart vaultwarden

👉 *Screenshot geeignet: Nano-Editor mit korrigierter DOMAIN-Zeile*

### Ich kann mich nicht im Adminbereich anmelden

- Rufe `https://pass.DEINE-DOMAIN.tld/admin` auf  
- Gib das Passwort ein, das du beim Erzeugen des Hashs vergeben hast

> [!NOTE]  
> Der Admin-Login funktioniert **nicht mit dem Hash**, sondern mit dem dazugehörigen Passwort.

Wenn du keinen Zugriff mehr hast:

- Neuen Hash erzeugen:

    docker exec -it vaultwarden /vaultwarden hash --preset owasp

- Hash im Adminbereich unter **Settings → General → Admin Token** einfügen  
- Container neu starten

👉 *Screenshot geeignet: Adminbereich mit Argon2 PHC Feld*

> [!WARNING]  
> Falls nichts mehr geht:  
> Vorübergehend `ADMIN_TOKEN=deinPasswort` in `.env` setzen → dann zurück auf Hash wechseln.


### Keine Live-Synchronisation zwischen Geräten

Wenn du Vaultwarden auf zwei Geräten gleichzeitig geöffnet hast und eine Änderung (z. B. ein neues Passwort) **nicht automatisch** auf dem anderen Gerät erscheint, liegt das fast immer an einer fehlenden WebSocket-Verbindung.

Vaultwarden verwendet WebSockets, um Änderungen sofort an alle verbundenen Geräte zu übertragen – ohne Neuladen.  
Damit das funktioniert, muss im Nginx Proxy Manager eine **zusätzliche Weiterleitung** eingerichtet sein.

Öffne den Proxy Host in NPM, der auf `pass.DEINE-DOMAIN.tld` zeigt:

1. Wechsle in den Reiter **Custom Locations**  
2. Stelle sicher, dass dort eine Weiterleitung für **`/notifications/hub`** eingerichtet ist  
3. Die Ziel-IP ist wie beim Haupt-Proxy `192.168.1.50`, aber der **Port ist `3012`**  
4. Aktiviere auch hier den Haken **„Websockets Support“**

> [!TIP]  
> Diese Weiterleitung ist zwingend erforderlich – ohne sie funktioniert die automatische Aktualisierung nicht.  
> Du musst dann manuell die Seite neu laden, um Änderungen zu sehen.

👉 *Screenshot geeignet: Custom Location mit Pfad `/notifications/hub`, Port 3012 und aktivem WebSocket-Haken*

---

## Zusammenfassung & Nächste Schritte

Mit Vaultwarden hast du jetzt einen vollwertigen Passwort-Manager im eigenen Homelab eingerichtet – sicher, unabhängig und kompatibel mit allen offiziellen Bitwarden-Apps.

### Was du jetzt erreicht hast:

- Vaultwarden läuft als Docker-Anwendung in einem eigenen Debian-LXC  
- Der Dienst ist über `https://pass.DEINE-DOMAIN.tld` erreichbar  
- Das Admin-Interface ist mit einem sicheren Hash-Zugang geschützt  
- Die WebSocket-Verbindung sorgt für Live-Synchronisierung  
- Backups sind eingerichtet und schnell wiederherstellbar

👉 *Screenshot geeignet: Loginmaske in Browser + aktiver Proxy Host in NPM*

> [!TIP]  
> Wenn du den Tresor auch unterwegs nutzen willst, installiere die Bitwarden-App auf deinem Smartphone  
> und stelle unter „Server-URL“ deine eigene Adresse ein:  
> `https://pass.DEINE-DOMAIN.tld`

> [!NOTE]  
> Du kannst Vaultwarden jetzt direkt im Alltag nutzen – zum Speichern von Passwörtern, Anlegen von Ordnern, Hinterlegen von TOTP-Codes und für sicheren Zugriff von überall.