init

docs/OPERATIONS.md

@@ -0,0 +1,72 @@
+# Betrieb, Abnahme und Wiederherstellung
+
+## Abnahme in Ihrer Infrastruktur
+
+1. Anmeldung als Leser und Operator prüfen; Leser dürfen keine Alarme quittieren.
+2. Einen echten Agenten und Collector anbinden; Host, Worker und Testtask kontrollieren.
+3. HTTPS-Verbindung des Agenten kurz sperren: Outbox wächst. Wieder öffnen:
+   Daten werden nachgeliefert, keine doppelten UUIDs. Alte Samples bleiben als alt erkennbar.
+4. Agent mit gefüllter Outbox neu starten und Nachlieferung prüfen.
+5. Django/UI und Flower separat neu starten. Historie im Dashboard und Flower prüfen.
+6. Host-Heartbeat unterbrechen; nach Timeout und Alarmzyklus Alarm prüfen.
+7. SMTP-Zustellung, Wiederholungen, Quittierung und automatische Auflösung prüfen.
+8. Datenbanksicherung in separater Datenbank wiederherstellen und Stichproben vergleichen.
+9. Mit erwarteter Host-/Task-Menge einen Lasttest ausführen; Aufbewahrung passend dimensionieren.
+10. Browser auf Desktop und Mobilgerät, TLS und WebSocket-Verbindung hinter Nginx prüfen.
+
+## Diagnostik
+
+```bash
+sudo systemctl status dilib-api dilib-ui dilib-worker dilib-beat
+sudo journalctl -u dilib-api -u dilib-ui -n 100 --no-pager
+sudo journalctl -u dilib-agent -n 100 --no-pager
+```
+
+Keine Werte: Token, HTTPS-Verbindung, Systemzeit/NTP und Agentlog prüfen.
+Keine Tasks: Broker-URL und aktivierte Celery-Events prüfen; Collector muss laufen.
+Keine Mails: Beat, Worker, SMTP und Empfängerliste prüfen.
+Flower offline: lokale URL, Authentifizierung und Dienst prüfen.
+Dauerhafter HTTP-400 beim Upload: invaliden Payload in der Outbox untersuchen;
+Agent blockiert den Batch absichtlich und löscht keine Daten ungeprüft.
+
+## Backup
+
+```bash
+sudo -u postgres bash /opt/dilib-dashboard/scripts/backup.sh /var/lib/postgresql/dilib-backups
+```
+
+Zusätzlich geschützt sichern: `/etc/dilib-dashboard`, `/etc/dilib-agent`,
+`/var/lib/dilib-dashboard` und Flower-Dateien. SQLite-Outbox nur bei gestopptem
+Agenten vollständig kopieren (einschließlich WAL-Dateien) oder SQLite-Backup-API nutzen.
+Flower vor Kopie seines Dateistands stoppen. Backups verschlüsselt extern aufbewahren.
+Automatische Backupplanung und externe Ausfallüberwachung betreiberseitig einrichten.
+
+Wiederherstellung zunächst in separate DB:
+
+```bash
+sudo -u postgres createdb --owner=dilib dilib_restore_test
+sudo -u postgres pg_restore --no-owner --role=dilib --dbname=dilib_restore_test /pfad/backup.dump
+```
+
+Für Umschaltung Dienste stoppen, DATABASE_URL auf geprüfte Wiederherstellung setzen,
+Migration prüfen und Dienste wieder starten. Keine laufende DB blind überschreiben.
+Nach Datenverlust können bereits bestätigte Agentenevents nicht erneut aus der Outbox
+rekonstruiert werden; RPO richtet sich nach Backup/WAL-Archivierungsstrategie.
+
+## Updates
+
+Backup anfertigen, Änderungen zuerst in Testumgebung prüfen, Dienste stoppen,
+Code aktualisieren, Requirements installieren, Migration und collectstatic ausführen,
+Dienste starten und Abnahmetests wiederholen. Getestete Paketstände stehen in
+`requirements.txt`; Versionsbereiche für bewusste Updates in `requirements.in`.
+
+## Lokale Prüfungen dieser Lieferung
+
+Prüfstand und Testanzahl: siehe VALIDATION.md. Tests umfassen: Authentifizierung und Ablauf, Rate Limit, Rollen, Batchvalidierung,
+Idempotenz, verspätete Task-Events, veraltete Hostwerte, Alarme/Quittierung,
+Retention, SMTP-Wiederholung, API/CSV/PNG sowie persistente Agent-Outbox/Redaktion.
+Tests liefen mit SQLite; PostgreSQL-Sperrverhalten und externe Integrationen sind
+nicht durch diesen lokalen Testlauf nachgewiesen.
+
+Die NiceGUI-Anwendung startete lokal ohne Startfehler. Eine visuelle Browserabnahme
+war hier mangels verfügbarer Browserinstallation nicht möglich.