# 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:

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

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

```bash
sudo systemctl status gateway
```

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

```bash
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:

```bash
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:

```bash
# 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:

```bash
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)

```bash
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

```bash
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:

```bash
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

```bash
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)

```bash
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.

```bash
# 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` |