7.2 KiB
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:
intstattmain - 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 |