diff --git a/docs/README.md b/docs/README.md index cd803ff..009eb8b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -33,6 +33,7 @@ | [TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md](product/TSUMUGU_CONNECTOR_NACHARBEIT_IMAP_PAPERLESS_MARKDOWN_AUFTRAG_2026-10-19.md) | Nacharbeit: IMAP-Seiten, Paperless-Suche, Markdown-Notiz | 19.10.2026 | | [TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md](product/TSUMUGU_KORREKTURAUFTRAG_CONNECTOREN_MAIL_MARKDOWN_2026-10-20.md) | Korrektur K1–K7: IMAP-Ordner, MIME, Transaktion, Markdown, Leser, Paperless-Antworten | 20.10.2026 | | [TSUMUGU_IMAP_SENT_ITEMS_MIME_BEFUND_UND_FIXAUFTRAG_2026-10-20.md](product/TSUMUGU_IMAP_SENT_ITEMS_MIME_BEFUND_UND_FIXAUFTRAG_2026-10-20.md) | Befund zu Sent Items und MIME, unverändert übernommen | 20.10.2026 | +| [TSUMUGU_RELEASE_GATE_BACKUP_AUFTRAG_2026-10-22.md](product/TSUMUGU_RELEASE_GATE_BACKUP_AUFTRAG_2026-10-22.md) | Auftrag P7: Release-Gate, Backup und Restore vor Produktion (R-21), für eine eigene Sitzung | 22.10.2026 | | [TSUMUGU_CONNECTOR_NACHARBEIT_REVIEW_2026-10-20.md](product/TSUMUGU_CONNECTOR_NACHARBEIT_REVIEW_2026-10-20.md) | Review der Nacharbeit, unverändert übernommen | 20.10.2026 | | [TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md](product/TSUMUGU_CONNECTOR_BASIS_ERGEBNIS_2026-10-19.md) | früherer Zwischenstand von Abschnitt A vor den Abschlusskriterien | 19.10.2026 | | [TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md](product/TSUMUGU_WEITERPLANUNG_UEBERGABE_2026-10-17.md) | Einstieg für die fachliche Weiterplanung | 17.10.2026 | diff --git a/docs/product/TSUMUGU_RELEASE_GATE_BACKUP_AUFTRAG_2026-10-22.md b/docs/product/TSUMUGU_RELEASE_GATE_BACKUP_AUFTRAG_2026-10-22.md new file mode 100644 index 0000000..f9487d4 --- /dev/null +++ b/docs/product/TSUMUGU_RELEASE_GATE_BACKUP_AUFTRAG_2026-10-22.md @@ -0,0 +1,65 @@ +# Auftrag: Release-Gate, Backup und Restore für Produktion (P7, Review R-21) + +**Stand:** 22.10.2026 · **Status:** Vorbereiteter Umsetzungsauftrag für eine eigene Sitzung, getrennt von der Fachentwicklung. Kein Push auf `main`, kein Eingriff in die laufende Produktion ohne ausdrückliche Freigabe. + +## 1. Ziel + +Bevor echte personenbezogene Daten in Produktion liegen, muss ein Merge nach `main` sicher sein. Heute baut `deploy-prod.yml` bei jedem Push auf `main` auf dem Host neu und startet die Produktion, ohne Test davor, ohne Backup und ohne Rückweg. Die Migrationen laufen beim Start des Backends und sind teils nicht umkehrbar (zum Beispiel entfernt `20261021T150000Z_room_shares.sql` die Spalten `visibility`). + +Gewünscht ist die Reihenfolge des Release-Blueprints: `develop → Dev → Tests → Freigabe → main → Prüfung des Kandidaten → Prod`. + +## 2. Lieferumfang + +1. **Release-Gate vor Produktion:** `deploy-prod` läuft nur, wenn die Tests für genau diesen Stand grün sind. Zusätzlich eine menschliche Freigabe (Gitea-`environment` allein ersetzt sie nicht, siehe Technische Spezifikation 8.2). Ein roter oder übersprungener Test gilt nie als Erfolg. +2. **Isolierter Testlauf:** Die Tests laufen gegen eine kurzlebige Datenbank je Lauf, nicht gegen die gemeinsame `tsumugu_test`, und nicht doppelt parallel (Review R-27). Der Testlauf prüft das gebaute Image, nicht einen Checkout im Laufzeitcontainer. +3. **Backup vor jeder Migration in Produktion:** konsistente Sicherung von PostgreSQL und Medien (`tsumugu-media`) zu einem gemeinsamen Zeitpunkt, mit Prüfsumme und dokumentiertem Zustand. Das Deploy bricht ab, wenn die Sicherung fehlschlägt. +4. **Aufbewahrung und unabhängige Kopie:** Startprofil laut Blueprint und Spezifikation: RPO 24 h, RTO 4 h, Sicherung alle zwölf Stunden, sieben tägliche, vier wöchentliche, drei monatliche Stände. Mindestens eine Kopie außerhalb des Hosts. Verschlüsselung der Sicherungen, der Schlüssel liegt getrennt vom Backup. +5. **Restore, geprobt:** Wiederherstellung in eine neue Umgebung (nicht über die laufende), zuerst mit synthetischen Daten auf Dev. Nach einem Restore sind alle Sitzungen ungültig, und die Konten werden vor der Freigabe geprüft (Auth-Blueprint 12). +6. **Rückweg bei fehlgeschlagenem Deploy:** Der Ablauf bei einer fehlgeschlagenen Migration oder einem nicht gesunden Start ist beschrieben und getestet: Prod bleibt auf dem alten Stand oder wird aus dem Backup zurückgeholt. +7. **Dokumentation:** `docs/DEPLOYMENT.md` und die Betriebsgrenzen werden fortgeschrieben, ein kurzes Runbook für Backup, Restore und Rückweg ergänzt. + +Nicht Teil: Fachfunktionen, ein Umbau der Anwendung, Hybrid- oder Cloud-Betrieb, ein externer Registry-Dienst (R1 mit Imageablage ist bevorzugt, bis dahin ein kontrollierter getrennter Build mit eigenem Gate für genau diesen Kandidaten). + +## 3. Grundlagen (zuerst lesen) + +- `AGENTS.md`, `docs/DEPLOYMENT.md`, `docs/ENTWICKLUNG_UND_TESTS.md`. +- `docs/reference/Jinkendo_Release_Betrieb_Recovery_Blueprint.md`, insbesondere Abschnitte 1, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13 und 15. Der Verzeichnisname ist `reference`, Singular. +- `docs/architecture/TSUMUGU_TECHNICAL_SPEC.md`, Paket P7 und Abschnitt 8.2. +- `docs/review/06_BEFUNDE.md` (R-21, R-23, R-27, R-09) und `docs/review/10_NACHPRUEFUNG_2026-10-20.md`. + +## 4. Ausgangslage im Repository + +- Workflows in `.gitea/workflows/`: `deploy-dev.yml` (Push auf `develop`), `deploy-prod.yml` (Push auf `main`), `test.yml` (Push auf `develop` und nach dem Dev-Deploy, gegen die feste Datenbank `tsumugu_test` der Dev-Postgres). +- Compose: `docker-compose.yml` (Produktion, Volumes `tsumugu-media` und Postgres) und `docker-compose.dev-env.yml` (Dev). Der Host ist ein Raspberry Pi; der Runner läuft dort. +- Migrationen führt das Backend beim Start aus (`backend/app/entrypoint.py`, `backend/app/db/migrate.py`): Ledger mit Prüfsumme, aber ohne Advisory-Lock, ohne Fehlend-Prüfung und mit denselben Zugangsdaten für Migration und Laufzeit (R-09). +- Tests: `powershell -File tests` laufen lokal gegen eine eigene PostgreSQL 16 (siehe Abschnitt 6). Zahl der Tests Stand 22.10.2026: 143. +- Es gibt kein Backup, keinen Restore und keinen Rückweg. + +## 5. Vorgehen und Grenzen + +1. Zuerst eine kurze Bestandsaufnahme: Was kann der Gitea-Server auf `192.168.2.144` an Branch-Schutz, Environments und Freigaben, und wie isoliert ist der Runner? Das ist laut Spezifikation ungeprüft. Ergebnis als kurze Notiz, bevor gebaut wird. +2. Reihenfolge der Arbeit: Testlauf isolieren → Backup und Restore auf Dev bauen und proben → Gate und Freigabe → Anbindung an `deploy-prod` → Rückweg → Runbook. +3. Produktion nicht anhalten und nicht verändern, bevor Backup und Restore auf Dev nachweislich funktionieren. Eine Änderung an `deploy-prod.yml` wird erst nach Freigabe auf `main` wirksam; bis dahin auf `develop` arbeiten. +4. Keine Zugangsdaten, Schlüssel oder Passwörter ins Repository. Secrets liegen in der Betriebsbereitstellung. +5. Vor jedem Push `git pull --rebase`. Die Fachentwicklung läuft parallel auf `develop` in `backend/app`, `frontend/src` und `docs/architecture`. Dieser Auftrag fasst vor allem `.gitea/workflows/`, `docker-compose*.yml`, Betriebsskripte und `docs/DEPLOYMENT.md` an. +6. Kein Push auf `main` und kein Merge ohne ausdrückliche Anweisung des Nutzers. Jede Aktion am Raspberry Pi (Anlegen von Verzeichnissen, Cron/Timer, Schlüssel) ist vorher zu benennen und freizugeben. + +## 6. Lokale Testumgebung + +Auf dem Entwicklungsrechner liegt eine isolierte Umgebung unter `C:\dev\tsumugu-local` (portable PostgreSQL 16 auf `127.0.0.1:55432`, Python 3.12, virtuelle Umgebung). Der Aufruf `powershell -File C:\dev\tsumugu-local\run-tests.ps1 tests` startet die Datenbank und führt die Suite aus (rund vier Minuten). Sie berührt keine Server. Die Testdatenbank muss auf `_test` enden; das erzwingt die Suite. + +## 7. Abnahme + +| Nr. | Nachweis | +|---|---| +| 1 | Ein roter Test oder ein fehlendes Backup verhindert das Produktions-Deploy; der Ablauf bricht ab und meldet den Grund. | +| 2 | Zwei gleichzeitige Testläufe stören sich nicht (eigene Datenbank je Lauf). | +| 3 | Eine Sicherung von Datenbank und Medien entsteht vor der Migration, mit Prüfsumme; Restore in eine neue Umgebung stellt beide wieder her. Das Ergebnis wird mit synthetischen Daten geprüft. | +| 4 | Nach dem Restore sind Sitzungen ungültig und Konten gesperrt, bis sie freigegeben sind. | +| 5 | Ein absichtlich fehlerhafter Migrationsstand auf Dev lässt die Umgebung nicht halb migriert zurück; der Rückweg ist beschrieben und geprobt. | +| 6 | Aufbewahrung und die Kopie außerhalb des Hosts sind eingerichtet und überprüft. | +| 7 | Runbook und `docs/DEPLOYMENT.md` sind aktuell. Reale Prod-Aktionen sind vom Nutzer freigegeben und im Bericht von synthetischen Nachweisen getrennt. | + +## 8. Übergabe + +Kurzer Abschlussbericht: je Lieferpunkt Ergebnis, ausgeführte Tests, was nur synthetisch nachgewiesen und was an Prod noch offen ist. Neue Dokumente in `docs/README.md` verlinken und die Befunde R-21 und R-27 im Review fortschreiben.