Secrets und Backups

Diese Seite beschreibt die dienstübergreifenden Regeln für Secrets, persistente Daten und Backups. Konkrete Datenpfade pro Dienst stehen zusätzlich auf den jeweiligen Dienstseiten.

Grundregeln für Secrets

Secrets werden nicht in der Dokumentation ausgeschrieben. Dazu gehören insbesondere:

• Passwörter
• API-Keys
• Tokens
• Session-Secrets
• Datenbank-URLs mit Passwortanteil
• SMTP-/IMAP-Zugangsdaten
• OAuth-Tokens

Die Dokumentation darf Secret-Namen und Speicherorte nennen, aber keine Werte.

Lokale Secret-Dateien

Aktuell werden mehrere Dienste über lokale .env-Dateien unter /opt/selfhost/secrets/ versorgt.

Konvention:

/opt/selfhost/secrets/<dienst>.env

Empfohlene Rechte:

sudo chown root:selfhost /opt/selfhost/secrets/<dienst>.env
sudo chmod 660 /opt/selfhost/secrets/<dienst>.env

Diese Dateien sind backuprelevant, dürfen aber nicht in öffentliche Repositories, HTML-Ausgaben oder Tickets kopiert werden.

Bekannte Secret-Dateien

Datei	Verwendung
/opt/selfhost/secrets/stalwart.env	Stalwart-Initial-/Betriebswerte
/opt/selfhost/secrets/bulwark.env	Bulwark-Konfiguration und Zugangsdaten/Secrets
/opt/selfhost/secrets/litellm.env	LiteLLM-Keys, Datenbankvariablen, UI-Login, Provider-/Callback-Konfiguration
/opt/selfhost/secrets/langfuse.env	Langfuse-, Datenbank-, ClickHouse- und MinIO-Secrets
/opt/selfhost/secrets/caddymanager.env	CaddyManager JWT_SECRET und sonstige geheime Werte

Die Liste dokumentiert Speicherorte, nicht Inhalte.

Bitwarden Secrets Manager

Langfristig ist Bitwarden Secrets Manager als Zielmodell vorgesehen. Auf diesem Server ist die EU-Cloud-Konfiguration relevant:

Variable	Wert
BWS_API_URL	https://vault.bitwarden.eu/api
BWS_IDENTITY_URL	https://vault.bitwarden.eu/identity

Das ist wichtig, weil SDKs und CLIs sonst standardmäßig die US-Endpunkte verwenden können. Die lokalen .env-Dateien sind deshalb als aktueller Betriebsstand und teilweise Übergangsmodell zu verstehen, nicht als endgültiges Ideal.

Persistente Daten

Persistente Daten sind alles, was bei Container-Neuerstellung erhalten bleiben muss. Dazu gehören:

• Anwendungsdatenbanken
• Uploads und Objektspeicher
• Konfigurationsdateien
• OAuth-Token-Verzeichnisse
• Benutzerkonten und Dienstzustände
• Monitoring- und Historienwerte

Typische Speicherorte:

/opt/selfhost/data/<dienst>/
/opt/selfhost/stacks/<dienst>/config/

Docker-Volumes sind ebenfalls persistent, aber weniger offensichtlich als Hostpfade. Wenn ein Stack benannte Docker-Volumes verwendet, muss die Dienstseite diese explizit nennen.

Backup-Relevanz nach Kategorien

Kategorie	Beispiele	Backup-Priorität
Identität/Zugriff	Dienst-Logins, API-Keys, OAuth-Tokens	sehr hoch
Mail	Stalwart-Konfiguration und Maildaten	sehr hoch
KI-Gateway	LiteLLM-Datenbank, OAuth-Tokens, Modellkonfiguration	hoch
Observability	Langfuse PostgreSQL/ClickHouse/MinIO	hoch
Admin-Tools	Portainer, Uptime Kuma, CaddyManager	mittel bis hoch
Generierte Artefakte	/opt/selfhost/generated/, /opt/selfhost/site/	niedrig, reproduzierbar

Lokaler Backup-Timer

Es gibt einen aktiven systemd-Timer:

selfhost-config-backup.timer

Er läuft täglich und erzeugt lokale Konfigurationsbackups. Lokale Backups ersetzen keine externe/offsite Sicherung, sind aber nützlich für schnelle Rückverfolgung und Wiederherstellung nach Konfigurationsfehlern.

Nützliche Befehle:

systemctl list-timers --all selfhost-config-backup.timer
systemctl status selfhost-config-backup.timer
systemctl status selfhost-config-backup.service

Was gesichert werden sollte

Mindestens backuprelevant sind:

/opt/selfhost/registry/routes.json
/opt/selfhost/stacks/
/opt/selfhost/data/
/opt/selfhost/secrets/
/opt/selfhost/docs/
/opt/selfhost/mkdocs.yml
/etc/caddy/Caddyfile
/opt/selfhost/generated/openclaw-error/

Bei /opt/selfhost/generated/ ist zu unterscheiden: Die meisten Dateien sind reproduzierbar. Die OpenClaw-Hinweisseite ist dagegen eine bewusst gepflegte statische Seite und sollte erhalten bleiben.

Was nicht als alleinige Quelle gelten sollte

Nicht als einzige Quelle sollten gelten:

• /opt/selfhost/site/, weil es aus MkDocs neu gebaut werden kann.
• /opt/selfhost/generated/caddy/routes.caddy, weil es aus routes.json neu generiert wird.
• /opt/selfhost/generated/homepage/services.yaml, weil es aus routes.json neu generiert wird.
• Container-Dateisysteme ohne Volume, weil sie bei Recreate verloren gehen können.

Wiederherstellungslogik

Eine grobe Wiederherstellung folgt dieser Reihenfolge:

1. Host-Basisdienste bereitstellen: Docker, Caddy, Tailscale.
2. /opt/selfhost mit Registry, Stacks, Daten, Secrets und Docs wiederherstellen.
3. Docker-Compose-Stacks starten.
4. Registry-Artefakte neu generieren.
5. Caddy validieren und reloaden.
6. MkDocs neu bauen.
7. Dienstweise prüfen: Mail, Agents, KI-Dienste, Admin-Oberflächen.

Dokumentationsregel

Dienstseiten sollen einen Abschnitt „Persistente Daten und Backups“ enthalten. Dort wird pro Dienst festgehalten:

• welche Hostpfade oder Docker-Volumes wichtig sind,
• welche Konfigurationsdateien dazugehören,
• welche Secret-Datei verwendet wird,
• ob Daten reproduzierbar oder kritisch sind.