9f5f8bfc11
Includes CACC/FINMA legal processes, updated AGB with PowerOn AG stammdaten, and internal legal and best-practice analysis report. Co-authored-by: Cursor <cursoragent@cursor.com>
204 lines
7.2 KiB
Markdown
204 lines
7.2 KiB
Markdown
# 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` |
|