feat(deploy): Wiederherstellung proben und Skript dafuer (#045)

Einer der vier Punkte bis 1.0.0: eine Sicherung einmal wirklich zurueckspielen. Mit einem eigenen Stapel durchgespielt - Datenstand festgehalten, Marke gesetzt, PDF abgelegt, gesichert, alle Volumes zerstoert, zurueckgespielt. Datenbank, PDF und Anmeldung waren zurueck. Zwei Luecken kamen erst dabei heraus: 1. Ohne --clean liess sich die Sicherung nur in eine LEERE Datenbank zurueckspielen - im Ernstfall also gerade nicht. Jetzt pg_dump --clean --if-exists, gegen eine Datenbank mit Daten geprueft. 2. Fuer die hochgeladenen PDFs gab es keinen beschriebenen Weg zurueck. deploy/restore.sh haelt die Dienste an, spielt Datenbank und PDFs zurueck, startet wieder und prueft die Erreichbarkeit. Die .env bleibt unangetastet: Sie traegt APP_SECRET, und ein falscher Wert dort macht gespeicherte Zugangsdaten unlesbar. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-10-10 19:31:35 +02:00
parent 8119aaad66
commit 409a02561d
9 changed files with 234 additions and 17 deletions
@@ -27,19 +27,51 @@ ruft es als Erstes auf und bricht ab, wenn es fehlschlägt.
 ## Zurückspielen

 ```bash
-# Docker
-docker compose down
-docker compose up -d postgres
-gunzip -c sicherung.sql.gz | docker compose exec -T postgres psql -U proxledger proxledger
+bash deploy/restore.sh /var/backups/proxledger            # jüngste Sicherung
+bash deploy/restore.sh /var/backups/proxledger 20261010-192437   # bestimmter Stand
+```
+
+Das Skript hält Dashboard und Worker an, spielt Datenbank **und** hochgeladene PDFs zurück, startet
+alles wieder und prüft, ob das Dashboard antwortet. Vorher fragt es nach; `--ja` überspringt die
+Rückfrage (für Skripte).
+
+Die `.env` fasst es bewusst **nicht** an: Sie trägt `APP_SECRET`, und ein falscher Wert dort macht die
+gespeicherten Zugangsdaten für SMTP und Webhook unlesbar. Die zum Stand passende Fassung liegt als
+`env-<Stand>.txt` in der Sicherung – im Zweifel von Hand vergleichen.
+
+### Von Hand, wenn es sein muss
+
+```bash
+docker compose stop web worker
+gunzip -c datenbank-20261010-192437.sql.gz | docker compose exec -T postgres psql -U proxledger proxledger
+docker compose run --rm -T --entrypoint tar web -xzf - -C / < uploads-20261010-192437.tar.gz
 docker compose up -d
 ```

-Danach die `.env` mit **demselben** `APP_SECRET` zurücklegen wie zum Zeitpunkt der Sicherung. Ein
-anderer Wert lässt die gespeicherten Zugangsdaten unlesbar werden; das Dashboard sagt das beim
-nächsten Versand deutlich, aber die Werte müssen dann neu eingetragen werden.
+Bei der Installation als Dienst stattdessen `psql "$DATABASE_URL"` und `tar -xzf … -C /opt/proxledger/data`.
+
+## Geprobt am 10.10.2026
+
+Nicht behauptet, sondern durchgespielt – mit einem eigenen Stapel:
+
+1. Stand festgehalten (9 Hosts, 4 Kunden, 10 Laufzeiten), ein Kunde zur Wiedererkennung umbenannt,
+   eine PDF-Datei abgelegt
+2. Sicherung angelegt
+3. **Alle Daten zerstört** (`docker compose down -v` – Datenbank und Upload-Volume weg)
+4. `deploy/restore.sh` aufgerufen
+
+Ergebnis: Datenbank vollständig zurück (die umbenannte Kundin war wieder da), die PDF-Datei lag mit
+den richtigen Rechten im Upload-Ordner, Anmeldung mit dem alten Passwort funktionierte.
+
+Dabei zwei Lücken gefunden und geschlossen: Die Sicherung ließ sich nur in eine **leere** Datenbank
+zurückspielen (jetzt `pg_dump --clean --if-exists`), und für die hochgeladenen PDFs gab es überhaupt
+keinen beschriebenen Weg.
+
+> Geprobt wurde der Docker-Weg. Für die Installation als Dienst ist derselbe Ablauf im Skript
+> vorgesehen, aber noch nicht unter echten Bedingungen gelaufen.

 ## Das Wichtigste

 **Eine Sicherung, die nie zurückgespielt wurde, ist keine Sicherung.** Spielen Sie sie einmal in eine
-leere Testumgebung ein und melden Sie sich dort an. Erst dann wissen Sie, dass Sicherung und
-`APP_SECRET` zusammenpassen.
+Testumgebung ein und melden Sie sich dort an. Erst dann wissen Sie, dass Sicherung und `APP_SECRET`
+zusammenpassen.
@@ -0,0 +1,40 @@
+# #045 Wiederherstellung proben und Skript dafür
+**Status:** erledigt
+**Meilenstein:** v0.27.0
+**Labels:** deployment, doku
+**Geschätzt:** 2 h   **Tatsächlich:** 0 h 50 min
+
+## Ziel
+Einer der vier Punkte bis 1.0.0: eine Sicherung **einmal wirklich zurückspielen**. Bis dahin war nur
+geprüft, dass `deploy/backup.sh` Dateien schreibt.
+
+## Ablauf der Probe
+Mit einem eigenen Docker-Stapel, getrennt von allen anderen Daten:
+
+1. Datenstand festgehalten (9 Hosts, 4 Kunden, 10 Laufzeiten), einen Kunden zur Wiedererkennung in
+   `Marke-192641` umbenannt, eine PDF-Datei in den Upload-Ordner gelegt
+2. Sicherung angelegt
+3. **Alle Daten zerstört** – `docker compose down -v`, also Datenbank- und Upload-Volume weg
+4. Zurückgespielt und geprüft
+
+**Ergebnis:** Datenbank vollständig zurück (die Marke war wieder da), die PDF-Datei lag mit den
+richtigen Rechten im Upload-Ordner, Anmeldung mit dem alten Passwort funktionierte.
+
+## Zwei Lücken, die erst die Probe gezeigt hat
+1. **Die Sicherung ließ sich nur in eine leere Datenbank zurückspielen.** `pg_dump` ohne `--clean`
+   scheitert an bestehenden Tabellen – genau im Ernstfall, wenn man in eine laufende Installation
+   zurückspielen will. Jetzt `--clean --if-exists`; gegengeprüft gegen eine Datenbank mit Daten:
+   null Fehlerzeilen, der zwischenzeitlich geänderte Wert war wieder auf dem Stand der Sicherung.
+2. **Für die hochgeladenen PDFs gab es keinen beschriebenen Weg.** Gesichert wurden sie, zurückspielen
+   musste man selbst herausfinden.
+
+## Ergebnis
+- `deploy/restore.sh`: hält die Dienste an, spielt Datenbank und PDFs zurück, startet wieder und prüft
+  die Erreichbarkeit. Fragt vorher nach, `--ja` überspringt das.
+- Die `.env` wird bewusst **nicht** überschrieben: Sie trägt `APP_SECRET`, und ein falscher Wert dort
+  macht die gespeicherten Zugangsdaten unlesbar. Die passende Fassung liegt als `env-<Stand>.txt` daneben.
+- `docs/betrieb/sicherung.md` beschreibt den geprobten Ablauf samt Handarbeit als Rückfallebene.
+
+## Offen
+Geprobt wurde der Docker-Weg. Für die Installation als Dienst ist derselbe Ablauf im Skript
+vorgesehen, aber noch nicht unter echten Bedingungen gelaufen.
@@ -48,4 +48,5 @@ Details und Architektur: [../architektur.md](../architektur.md). Zeiten werden a
 | [#042](042-qdevice-cluster.md) | Cluster-Knoten falsch gelesen bei QDevice | erledigt | v0.24.1 | 1 h | 0 h 20 min |
 | [#043](043-laufzeiten-bearbeiten.md) | Laufzeiten anlegen, bearbeiten, zusammenführen | erledigt | v0.25.0 | 4 h | 1 h 05 min |
 | [#044](044-eigenbedarf.md) | Eigene Hosts ohne Weiterberechnung | erledigt | v0.26.0 | 2 h | 0 h 40 min |
-| | **Summe** | | | **175 h** | **24 h 38 min** |
+| [#045](045-wiederherstellung-geprobt.md) | Wiederherstellung proben und Skript dafür | erledigt | v0.27.0 | 2 h | 0 h 50 min |
+| | **Summe** | | | **177 h** | **25 h 28 min** |
@@ -1,6 +1,6 @@
 # Roadmap

-Stand: 04.10.2026, Fassung 0.26.0
+Stand: 10.10.2026, Fassung 0.27.0

 Die erste Fassung dieser Roadmap entstand vor dem produktiven Einsatz. Seitdem läuft ProxLedger mit
 echten Daten, und das hat die Reihenfolge deutlich verändert: Was aus der Benutzung kam, war fast
@@ -26,7 +26,7 @@ Kein neuer Funktionsumfang – es fehlt Erprobung.
 |---|---|---|
 | **PMG im Feldtest** ([#023](issues/023-feldtest-pbs-pmg.md)) | Der einzige Produktzweig ohne echten Host. Bei PBS lag die Annahme daneben, und der Agent hätte dort nichts gemeldet. | 1 h, sobald ein Host da ist |
 | **PBS mit aktiver Lizenz** | Bisher nur „keine Subscription“ geprüft. | 30 min |
-| **Sicherung einmal zurückspielen** | Eine Sicherung, die nie zurückgespielt wurde, ist keine. | 30 min |
+| ~~Sicherung einmal zurückspielen~~ | **Erledigt am 10.10.2026** ([#045](issues/045-wiederherstellung-geprobt.md)) – dabei kamen zwei Lücken heraus. Offen bleibt die Probe für die Installation als Dienst. | – |
 | **Ein Lizenzjahr durchlaufen lassen** | Warnung → Verlängerung → Einkauf → Kundenrechnung → bezahlt, einmal vollständig in echt. Die nächsten Abläufe stehen am 17.10.2026 an. | nur Zeit |

 ---