Homelab--Bratonein-Kontrollzentrum--Tutorial/Kapitel 6/Tutorial.md

🛠️ 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

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

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:

docker --version && docker compose version

👉 Offizielle Pakete, Compose als Plugin integriert.

— — —

3️⃣ Projekt anlegen & .env erstellen

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

nano docker-compose.yml

Inhalt einfügen:

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

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):

   # 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).

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

4. Prüfen:

   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)

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).