wiki/e-compliance/Prozesse/20260528_bcm_runbook.md

Runbook: Plattform-Core (PowerOn Gateway)

Dieses Dokument beschreibt die drei häufigsten Betriebsszenarien für die PowerOn-Plattform. Es richtet sich an alle, die im Notfall handeln müssen — auch ohne tiefes technisches Vorwissen. Die konkreten Befehle sind für die Person gedacht, die den Server-Zugang hat (typisch: Entwickler oder DevOps).

Kurze Systemübersicht: Die Plattform läuft auf einem Server bei Infomaniak (api.poweron.swiss). Alle Kundendaten liegen in einer separaten PostgreSQL-Datenbank (db.poweron.swiss). Codeänderungen werden über das interne Git-System (Forgejo) automatisch deployed.

Umgebung	Server	URL
Produktion	ubuntu@api.poweron.swiss	https://api.poweron.swiss
Integration (Test)	ubuntu@api-int.poweron.swiss	https://api-int.poweron.swiss

---

1. Produktivumgebung neu starten

Wann nötig? Die API antwortet nicht mehr, Requests laufen in Timeouts, oder nach einem Konfigurationswechsel soll alles frisch gestartet werden.

Was passiert dabei? Der laufende Prozess wird gestoppt und neu gestartet. Die Datenbank und alle gespeicherten Daten bleiben dabei vollständig erhalten. Nutzer merken einen kurzen Unterbruch von typisch wenigen Sekunden.

Normalfall: Service neu starten

Auf dem Produktionsserver einloggen und den Service neu starten:

ssh ubuntu@api.poweron.swiss
sudo systemctl restart gateway

Danach prüfen, ob alles wieder läuft:

sudo systemctl status gateway

Den Health-Check aufrufen — wenn er 200 OK zurückgibt, ist alles gut:

curl https://api.poweron.swiss/api/admin/health

Kompletter Neustart (inkl. Abhängigkeiten neu laden)

Wenn sich seit dem letzten Deploy neue Bibliotheken geändert haben oder nach einem manuellen Eingriff am Server:

ssh ubuntu@api.poweron.swiss
cd /srv/gateway/current
source .venv/bin/activate
pip install -r requirements.txt --no-cache-dir
sudo systemctl restart gateway

Wenn der Service nicht startet

Wenn der Neustart nicht hilft oder der Service sofort wieder abbricht, hilft ein Blick in die Logs:

# Systemlogs der letzten 100 Zeilen
sudo journalctl -u gateway -n 100 --no-pager

# Anwendungslogs des heutigen Tages
tail -100 /srv/gateway/shared/logs/log_app_$(date +%Y%m%d).log

Wenn der Fehler unklar ist, kann die App auch direkt im Vordergrund gestartet werden — dann erscheint die Fehlermeldung sofort im Terminal:

cd /srv/gateway/current
source .venv/bin/activate
gunicorn app:app --bind 0.0.0.0:8000 --timeout 600 \
  --worker-class uvicorn.workers.UvicornWorker --workers 1

---

2. Backup einspielen (Datenbankwiederherstellung)

Wann nötig? Nach einem Datenverlust, einer fehlerhaften Migration oder wenn ein früherer Datenbankstand wiederhergestellt werden muss.

Was passiert dabei? Die Anwendung wird kurz gestoppt, damit während dem Restore niemand inkonsistente Daten sieht. Die bestehenden Daten werden durch den Backup-Stand ersetzt. Danach wird die Anwendung wieder gestartet. Je nach Datenmenge dauert der Restore wenige Minuten bis zu einer Stunde.

Wichtig vor dem Start: Immer zuerst einen aktuellen Snapshot erstellen, bevor man ein älteres Backup einspielt — so kann man auch den Zustand kurz vor dem Restore noch wiederherstellen, falls etwas schiefläuft.

Schritt 1: Aktuellen Stand sichern (Sicherheitskopie)

ssh ubuntu@api.poweron.swiss
# DB-Passwort aus der Konfiguration lesen:
grep DB_ /srv/gateway/current/.env

# Alle Datenbanken sichern (Dateien landen in /tmp/)
for DB in poweron_app poweron_management poweron_billing poweron_chat \
           poweron_chatbot poweron_trustee poweron_realestate \
           poweron_knowledge poweron_workspace; do
  pg_dump -h db.poweron.swiss -U poweron_dev -p 5432 \
    -Fc $DB > /tmp/backup_${DB}_$(date +%Y%m%d_%H%M%S).dump
done

Schritt 2: Anwendung stoppen und Backup einspielen

sudo systemctl stop gateway

# Einzelne Datenbank wiederherstellen (Beispiel: poweron_app)
pg_restore -h db.poweron.swiss -U poweron_dev -p 5432 \
  -d poweron_app --clean --if-exists \
  /pfad/zum/backup_poweron_app_DATUM.dump

sudo systemctl start gateway

Backup einspielen über das Migrations-Tool (alle Datenbanken)

Wenn ein vollständiges JSON-Export aus dem projekteigenen Migrationstool vorliegt:

ssh ubuntu@api.poweron.swiss
cd /srv/gateway/current
source .venv/bin/activate
sudo systemctl stop gateway

# Hilfe zum Import-Script anzeigen:
python scripts/script_db_export_migration.py --help

sudo systemctl start gateway

Schritt 3: Verifizieren

sudo systemctl status gateway
curl https://api.poweron.swiss/api/admin/health

---

3. Rollback auf die vorherige Version

Wann nötig? Ein frisch deploytes Update verursacht Fehler oder unerwünschtes Verhalten, das vorher nicht da war. Statt stundenlang zu debuggen, fährt man die Plattform einfach auf den letzten stabilen Stand zurück.

Was passiert dabei? Der Code auf dem Server wird auf einen früheren Git-Commit zurückgesetzt. Die Datenbank bleibt unverändert — nur der Anwendungscode wird ausgetauscht. Das dauert typisch unter 2 Minuten.

Hinweis zu Datenbank-Migrationen: Wenn das neue Update auch Datenbankänderungen enthielt, kann ein reiner Code-Rollback zu Inkompatibilitäten führen. In diesem Fall zusätzlich einen Datenbank-Restore (Szenario 2) in Betracht ziehen und vorher mit dem Entwicklungsteam absprechen.

Rollback über Git (empfohlen, schnellster Weg)

ssh ubuntu@api.poweron.swiss
cd /srv/gateway/current

# Die letzten 10 Deployments anzeigen — den gewünschten HASH notieren
git log --oneline -10

# Auf den gewählten Stand zurücksetzen (HASH ersetzen, z.B. "b04211be")
git reset --hard <COMMIT_HASH>

# Konfigurationsdatei neu setzen
test -f env-prod.env && cp env-prod.env .env && rm -f env-*.env

# Abhängigkeiten prüfen
source .venv/bin/activate
pip install -r requirements.txt --no-cache-dir

# Service neu starten und prüfen
sudo systemctl restart gateway
sudo systemctl status gateway
curl https://api.poweron.swiss/api/admin/health

Rollback über Forgejo (sauberer, hinterlässt Protokoll)

Diese Variante ist etwas langsamer (Tests laufen durch), aber der Rollback wird im Git-Verlauf sichtbar und ist für alle nachvollziehbar.

# Lokal: einen Revert-Commit erstellen und pushen
git revert HEAD  # oder den spezifischen Commit angeben
git push origin main
# → Forgejo startet automatisch Tests und deployed danach

Rollback auf der INT-Umgebung

Gleiche Schritte wie oben, aber mit diesen Werten:

• Server: ubuntu@api-int.poweron.swiss
• Branch: int statt main
• Env-Datei: env-int.env
• Health-Check: https://api-int.poweron.swiss/api/admin/health

---

Referenz

Was	Wo
Prod-Server	ubuntu@api.poweron.swiss
Int-Server	ubuntu@api-int.poweron.swiss
App-Pfad auf Server	/srv/gateway/current
App-Logs	/srv/gateway/shared/logs/log_app_YYYYMMDD.log
System-Logs	journalctl -u gateway
Datenbank-Host	db.poweron.swiss:5432
Datenbank-User	poweron_dev
Health-Check Endpoint	GET /api/admin/health
CI/CD Pipeline	.forgejo/workflows/main_porta-main-platform-core.yml