# Restore Handbook - KalliLab CORE

Stand: 2026-05-07

Dieses Handbuch ist die praktische Betriebsanleitung fuer Restore-Checks und Restore-Lab in KalliLab CORE.

Es ergaenzt:

- `docs/RESTORE_MATRIX.md`
- `docs/DISASTER_RECOVERY.md`
- `ops/restore-tests/*`

---

## 1. Ziel

Dieses Handbuch beantwortet vier Fragen:

1. Was ist die Restore-Quelle?
2. Wo wird getestet?
3. Wie pruefen wir Erfolg?
4. Wie machen wir das regelmaessig mit wenig Handarbeit?

---

## 2. Grundmuster

Alle validierten Restore-Tests folgen demselben Muster:

- Quelle bleibt das produktive Borg-Repo bei Hetzner
- Borg-Zugriff laeuft ueber den vorhandenen `borg-ui`-Container
- Passphrase kommt aus `/mnt/user/appdata/secrets/borg_repo_passphrase.txt`
- Testdaten landen unter `/mnt/user/backups/restore-lab/<dienst>`
- Reports landen unter `/mnt/user/backups/restore-reports`
- Testinstanzen laufen lokal ohne Traefik und ohne produktive Domain
- nach Erfolg werden Testcontainer und Testdaten wieder entfernt

---

## 3. Bereits praktisch verifiziert

### Vaultwarden

- Report: `/mnt/user/backups/restore-reports/vaultwarden-2026-05-07.md`
- Nachweis:
  - Borg-Restore erfolgreich
  - Testcontainer startete
  - Login-Seite war erreichbar

### Gitea

- Report: `/mnt/user/backups/restore-reports/gitea-2026-05-07.md`
- Nachweis:
  - Borg-Restore erfolgreich
  - Web-UI antwortete
  - SSH-Port reagierte

### Paperless

- Report: `/mnt/user/backups/restore-reports/paperless-2026-05-07.md`
- Nachweis:
  - Borg-Datei-Restore erfolgreich
  - Paperless-Dump aus Borg importiert
  - Login-Seite war erreichbar
  - Test-DB enthielt `25` Dokumente

---

## 4. Verzeichnisstruktur

### Produktiv

- `/mnt/user/appdata`
- `/mnt/user/services`
- `/mnt/user/documents`
- `/mnt/user/backups/borg/dumps/latest`

### Restore-Lab

- `/mnt/user/backups/restore-lab/vaultwarden`
- `/mnt/user/backups/restore-lab/gitea`
- `/mnt/user/backups/restore-lab/paperless`

### Reports

- `/mnt/user/backups/restore-reports`

---

## 5. Restore-Frequenz

- jeden Montag, 06:30:
  - Frische-Check fuer Dumps und Reports
- 1. Samstag im Monat, 07:00:
  - Vaultwarden
- 3. Samstag im Monat, 07:00:
  - Gitea
- jeder 2. Monat, 2. Samstag, 08:00:
  - Paperless

---

## 6. Betriebsmodi

### V1

- validierte Bash-Host-Jobs
- Host-Job-Definitionen liegen im Repo
- Scheduler kann bereits echte Frische- und Restore-Checks fahren
- `ntfy` und Hermes-Auswertung folgen danach

### V2

- `ntfy` bei Erfolg/Fehler
- Hermes liest Reports und baut Uebersichten
- zusaetzliche Rotation, Sammelreports und weitere Dienste

---

## 7. User Script Jobs auf Unraid

Die Vorlagen stehen in:

- `ops/restore-tests/unraid-user-scripts.md`

Host-Repo-Pfad:

```text
/mnt/user/services/homelab
```

V1-Jobs:

1. `restore-freshness-weekly`
2. `restore-vaultwarden-monthly`
3. `restore-gitea-monthly`
4. `restore-paperless-bimonthly`

---

## 8. Erfolgskriterien

Ein Restore-Test gilt nur dann als erfolgreich, wenn:

- Restore-Quelle lesbar war
- Daten im Restore-Lab ankamen
- Testcontainer startete
- Smoke-Test erfolgreich war
- Report geschrieben wurde

Nur `Container laeuft` reicht nicht.

---

## 9. Sicherheitsregeln

- keine produktiven Pfade beschreiben
- keine produktiven Container fuer Restore-Tests verwenden
- keine produktiven Domains fuer Testinstanzen verwenden
- keine Secrets im Repo
- keine Restore-Automatik fuer neue Dienste ohne bewusste Freigabe

---

## 10. Schnellstart

### Frische-Check

Auf dem Unraid-Host:

```bash
bash /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.sh freshness
```

### Vaultwarden Restore-Check

```bash
bash /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.sh vaultwarden
```

### Gitea Restore-Check

```bash
bash /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.sh gitea
```

### Paperless Restore-Check

```bash
bash /mnt/user/services/homelab/ops/restore-tests/run-restore-checks.sh paperless
```

### Optional mit `ntfy`

```bash
bash /mnt/user/services/homelab/ops/restore-tests/run-restore-job-with-ntfy.sh freshness homelab-info
```

---

## 11. Naechste Ausbaustufen

1. Vollautomatik fuer Vaultwarden, Gitea und Paperless
2. `ntfy`-Meldungen fuer Erfolg/Fehler
3. Hermes-Zusammenfassung ueber vorhandene Reports
4. naechster Referenz-Restore fuer `mail-archiver` oder `mealie`