🛠️ Kapitel 6 – Vaultwarden (Docker, Debian‑12‑LXC) – Tutorial

🎯 Ziel
Vaultwarden in einem Debian‑12‑LXC per **Docker + Compose** bereitstellen, hinter **Nginx Proxy Manager** (NPM) mit **HTTPS** und **WebSockets** veröffentlichen; **Registrierungen deaktivieren**, **Admin‑Token** setzen und **Backups** ermöglichen.

🧩 Was wir aufbauen

* **Image:** `vaultwarden/server:latest`
* **Ports:** `8000:80` (Web/API), `3012:3012` (WebSocket/Live‑Sync)
* **Persistenz:** `./data:/data` → Hostpfad `/opt/vaultwarden/data`
* **Konfig per `.env`:** `DOMAIN`, `ADMIN_TOKEN`, `SIGNUPS_ALLOWED=false` (+ optional `SMTP_*`)
* **Reverse‑Proxy (NPM):** Proxy Host für `pass.DEINE‑DOMAIN.tld`, Custom Location `/notifications/hub → 3012`, SSL (Let’s Encrypt)

✅ Voraussetzungen (konkret)

* **LXC:** Debian 12 (Bookworm) – erstellt nach Grundkapitel *Erster LXC – Grundsetup & SSH* (hier nur Verweis)
* **Specs:** 1 vCPU · **512 MB–1 GB RAM** (512 MB empfohlen) · **4–8 GB Disk** · **statische IPv4** (z. B. `10.0.0.16/24`), IPv6 optional
* **NPM** läuft (separater LXC), **Subdomain** `pass.DEINE‑DOMAIN.tld` zeigt auf NPM (DNS A/AAAA gesetzt)
* **Outbound‑Internet** im LXC erreichbar; **Hostports 8000/3012** frei

🔁 Platzhalter

* `<VW_IP>` = IP des Vaultwarden‑LXC (z. B. `10.0.0.16`)
* `DEINE-DOMAIN.tld` = deine echte Domain

— — —

1️⃣ System vorbereiten

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

👉 `ca-certificates`/`curl`/`gnupg` werden für das Docker‑Repo benötigt.

— — —

2️⃣ Docker & Compose installieren

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

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

apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
systemctl enable --now docker
```

**Prüfen:**

```bash
docker --version && docker compose version
```

👉 Offizielle Pakete, Compose als Plugin integriert.

— — —

3️⃣ Projekt anlegen & `.env` erstellen

```bash
mkdir -p /opt/vaultwarden && cd /opt/vaultwarden
mkdir -p data
openssl rand -base64 48   # Token erzeugen und kopieren
nano .env
```

**Inhalt (`.env`) – Platzhalter ersetzen, Token einfügen:**

```
DOMAIN=https://pass.DEINE-DOMAIN.tld
ADMIN_TOKEN=HIER_DEIN_ERZEUGTES_TOKEN_EINFÜGEN
SIGNUPS_ALLOWED=false
# Optional SMTP (nur falls Mailversand gewünscht)
# SMTP_HOST=smtp.example.com
# SMTP_FROM=pass@example.com
# SMTP_PORT=587
# SMTP_SECURITY=starttls
# SMTP_USERNAME=user
# SMTP_PASSWORD=deinPasswort
```

**Speichern:** `Strg+O`, `Enter` → Beenden: `Strg+X`.
👉 `DOMAIN` zwingend **https**; `ADMIN_TOKEN` schützt `/admin`; Signups sind zu.

— — —

4️⃣ `docker-compose.yml` schreiben

```bash
nano docker-compose.yml
```

**Inhalt einfügen:**

```yaml
services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: unless-stopped
    env_file: .env
    environment:
      - DOMAIN=${DOMAIN}
    volumes:
      - ./data:/data
    ports:
      - "8000:80"     # Web / API
      - "3012:3012"   # WebSocket (Live Sync)
```

**Speichern:** `Strg+O`, `Enter` → `Strg+X`.
👉 `./data:/data` = Persistenz auf dem Host.

— — —

5️⃣ Container starten & Logs prüfen

```bash
docker compose up -d
docker compose logs -f --tail=50 vaultwarden
```

Erwartet: Meldungen wie `Rocket has launched…`.
👉 Erst prüfen, dann veröffentlichen.

— — —

6️⃣ NPM einrichten (Proxy, WebSockets, SSL)
**Proxy Host:**

* **Domain Names:** `pass.DEINE-DOMAIN.tld`
* **Scheme:** `http`
* **Forward Host/IP:** `<VW_IP>`
* **Forward Port:** `8000`
* **Block Common Exploits:** ✔️  · **Websockets Support:** ✔️

**Custom Location:**

* **Location:** `/notifications/hub`
* **Forward Host/IP:** `<VW_IP>`
* **Forward Port:** `3012`
* **Websockets Support:** ✔️

**SSL‑Tab:**

* **Request a new SSL Certificate (Let’s Encrypt)**
* **Force SSL**, **HTTP/2**, **HSTS**: ✔️

**Test:** `https://pass.DEINE-DOMAIN.tld` → Loginseite sichtbar; Live‑Änderung zwischen zwei Clients testen.
👉 Die Custom‑Location leitet den WebSocket‑Kanal (Live‑Sync) korrekt weiter.

— — —

7️⃣ Admin‑Backend (GUI), Admin‑Token absichern & erster Nutzer
Öffne `https://pass.DEINE-DOMAIN.tld/admin` und melde dich **mit deinem bisherigen Admin‑Token** an (zunächst im Klartext aus `.env`).

**A) Admin‑Token auf Argon2 PHC umstellen (GUI, sicher)**

1. **Hash erzeugen** (nimmt dein künftiges Admin‑Passwort entgegen → zweimal eingeben):

   ```bash
   # Container-Name ist im Tutorial 'vaultwarden'
   docker exec -it vaultwarden /vaultwarden hash --preset owasp
   ```

   > Kopiere **den kompletten PHC‑String** ab `$argon2id$…` (ohne zusätzliche Anführungszeichen).
2. **Im Admin‑Panel speichern:**

   * Admin → **Settings** → **General** → Feld **“Admin token / Argon2 PHC”**
   * PHC‑String einfügen → **Save**.
3. **Konflikte vermeiden:** Entferne das alte `ADMIN_TOKEN` aus der `.env` (wir nutzen künftig die **GUI‑Konfig**/`config.json`).

   ```bash
   cd /opt/vaultwarden
   sed -i '/^ADMIN_TOKEN=/d' .env
   docker compose restart vaultwarden
   ```
4. **Prüfen:**

   ```bash
   docker compose logs --tail=100 vaultwarden | grep -F "plain text `ADMIN_TOKEN`" || echo "✅ Admin‑Token ist als Argon2 PHC aktiv"
   ```

   **Login‑Hinweis:** Ab jetzt loggst du dich im Admin‑Bereich mit **dem Klartext‑Passwort** ein, das du beim `hash` eingegeben hast (nicht mit dem langen PHC‑String!).

**B) Ersten Benutzer per GUI anlegen (ohne SMTP)**

1. Admin → **Settings → General** → **Allow new signups** **einschalten** → **Save**.
2. In neuem Tab `https://pass.DEINE-DOMAIN.tld/#/register` öffnen → Benutzer anlegen → anmelden.
3. Admin → **Allow new signups** wieder **ausschalten** → **Save**.

   > **Mit SMTP** kannst du stattdessen Admin → **Users → Invitations** nutzen (Einladungs‑Mail).

**C) Sicherheit abrunden**

* Eigenes Benutzerkonto → **Settings/Security** → **2FA** (TOTP oder FIDO2/YubiKey) aktivieren.
* Optional: **SMTP** in Admin‑Panel setzen und **Testmail** senden.

— — —

8️⃣ Backup (Basis)

```bash
cd /opt/vaultwarden
# optional: kurz stoppen für maximale Konsistenz
# docker compose stop vaultwarden

tar -czf /root/vaultwarden-backup-$(date +%F).tar.gz data
# docker compose start vaultwarden
ls -lh /root/vaultwarden-backup-*.tar.gz
```

👉 Ein Tar reicht als Grundlage; regelmäßig per Cron sichern.

— — —

🛠️ Fehlerhilfe (kurz)

* **Kein Live‑Sync / 502:** NPM‑Location `/notifications/hub` → Port **3012** + **Websockets** ✔️
* **Icons/Links fehlen:** In `.env` `DOMAIN` = **https**; dann `docker compose restart vaultwarden`
* **Container startet nicht:** `docker compose logs --tail=200 vaultwarden`
* **Let’s‑Encrypt‑Fehler:** DNS‑Eintrag prüfen; Rate‑Limit abwarten

✅ Ergebnis

* Vaultwarden läuft hinter NPM mit **HTTPS**; **WebSockets** funktionieren
* **Registrierungen aus**, Admin‑Backend per **Token** geschützt
* Daten persistent unter `/opt/vaultwarden/data` und per Tar gesichert

— — —

9️⃣ Arbeiten mit Vaultwarden – Kurzguide (Praxis)

> **Ziel:** Direkt nach der Einrichtung sicher starten. Du brauchst nur deine URL `https://pass.DEINE-DOMAIN.tld`.

### 9.1 Anmelden & Clients verbinden

* **Web:** Öffne `https://pass.DEINE-DOMAIN.tld`, logge dich mit deinem Benutzer ein.
* **Browser‑Erweiterung:** Suche nach *Bitwarden* im Add‑on‑Store deines Browsers, installiere das Add‑on.

  * In den Add‑on‑Einstellungen **„Self‑Hosted/Server‑URL“** auf `https://pass.DEINE-DOMAIN.tld` setzen.
  * Einloggen → das Tresorsymbol erscheint in der Toolbar.
* **Desktop/Mobile (optional):** Bitwarden‑App installieren → beim ersten Start **Server** auf `https://pass.DEINE-DOMAIN.tld` stellen → einloggen.
  **Erfolg:** Du siehst deinen (noch leeren) Tresor in Web & Add‑on.

### 9.2 Ersten Eintrag anlegen (Login)

Web‑UI → **Neu** → **Anmeldung**:

* **Name:** z. B. „Twitch – Hauptaccount“
* **Benutzername / E‑Mail** und **Passwort** eintragen
* **URL:** z. B. `https://www.twitch.tv`
  Speichern.
  **Erfolg:** Der Eintrag erscheint sofort; das Add‑on zeigt ihn ebenfalls (Live‑Sync).

### 9.3 Ordner/Struktur

Web‑UI → **Ordner** → **Neuer Ordner**: z. B. „Streaming“.
Im Eintrag den **Ordner** auf „Streaming“ stellen → speichern.
**Warum:** Ordnung hält die Suche schlank.

### 9.4 Sicheres Passwort generieren

Web‑UI oder Add‑on → **Generator**:

* Länge **20–24**, **Zahlen**, **Sonderzeichen** an; **keine ähnlichen Zeichen**.
* „Generieren“ → „In Eintrag übernehmen“ (oder **Kopieren** und ins Zielkonto einfügen).
  **Tipp:** Nach Passwortwechsel beim Dienst die Änderung **im Tresor speichern**.

### 9.5 TOTP (2‑Faktor) im Eintrag hinterlegen

Beim Ziel‑Dienst 2FA aktivieren → du bekommst einen **TOTP‑Schlüssel** (Base32) oder **QR**.

* Im Tresor‑Eintrag → **Feld hinzufügen** → **„Authenticator‑Schlüssel (TOTP)“** wählen → Schlüssel einfügen → speichern.
* Der Eintrag zeigt nun **zeitbasierte 6‑stellige Codes**.
  **Test:** Logout beim Dienst → Login mit Passwort + aktuellem Code aus dem Eintrag.

### 9.6 Import vorhandener Passwörter (optional)

Web‑UI → **Werkzeuge** → **Importieren**:

* **Format** wählen (z. B. Chrome/Firefox/Bitwarden JSON/CSV).
* Datei auswählen → **Import**.
  **Hinweis:** Nach dem Import kurz durchgehen, doppelte/alte Logins aufräumen.

### 9.7 Autofill testen (Browser‑Add‑on)

Zur Login‑Seite wechseln → Tresorsymbol → passenden Eintrag anklicken → Felder werden gefüllt.
**Tipp:** In den Add‑on‑Einstellungen „Beim Seitenaufruf vorschlagen/Auto‑Fill“ nach Wunsch aktivieren.

### 9.8 „Send“ (sicher teilen, optional)

Web‑UI → **Neu** → **Send**:

* Text oder Datei wählen, **Ablaufdatum**, **max. Abrufe**, optional **Kennwort** setzen → **Erstellen** → **Link kopieren**.
  **Einsatz:** Einzelne Secrets/Dateien sicher an Partner schicken.

### 9.9 Organisation (Team, optional)

Web‑UI → **Organisationen** → **Neue Organisation** (Name vergeben).

* Mitglieder einladen (erfordert **funktionierendes SMTP**).
* **Sammlungen** anlegen (z. B. „Stream‑Zugänge“) und Einträge zuordnen.
  **Hinweis:** Ohne SMTP später nachrüsten; bis dahin Solo‑Tresor nutzen.

### 9.10 Export (Nutzer‑Sicht) & Restore‑Probe

Web‑UI → **Werkzeuge** → **Exportieren** → Format wählen (z. B. Bitwarden JSON) → lokal verschlüsselt ablegen.
**Probe‑Restore:** In einer Testinstanz/Profil importieren und prüfen. (Server‑Backups hast du zusätzlich in Schritt 8.)

### 9.11 Gute Praxis

* **Ein Dienst = ein eindeutiges Passwort**; Passwortgenerator konsequent nutzen.
* Wo verfügbar, **2FA aktivieren** und TOTP im Eintrag hinterlegen.
* Add‑on/Apps: **Sperre/Timeout** und **Biometrie/PIN** aktivieren.
* Regelmäßig **aufräumen** (alte/duplizierte Logins löschen).