RollCalcPython/docs/DEPLOYMENT_GUIDE.md

Deployment Guide

Dieses Dokument beschreibt den empfohlenen Ablauf für das Deployment von RollCalc auf dem Beta- oder Produktivserver.

---

Deployment Checklist

Vor Abschluss eines Deployments sollten alle folgenden Punkte erfüllt sein:

• Repository aktualisiert
• Python-Abhängigkeiten installiert
• config/users.json vorhanden und lesbar
• build_info.json geprüft bzw. aktualisiert
• RollCalc-Service erfolgreich neu gestartet
• Smoke-Test erfolgreich durchgeführt

---

Voraussetzungen

Erwartete Serverstruktur:

• Projektverzeichnis

/var/www/html

• Python Virtual Environment

/opt/rollcalc-venv

• systemd-Service

rollcalc.service

---

Deployment

1. Repository aktualisieren

cd /var/www/html

git fetch origin
git switch develop/v0.4
git pull --ff-only origin develop/v0.4

---

2. Python-Abhängigkeiten aktualisieren

Neue Python-Abhängigkeiten werden ausschließlich in der virtuellen Umgebung installiert.

sudo /opt/rollcalc-venv/bin/python \
    -m pip install -r requirements.txt

---

3. Benutzerdatei prüfen

Die Datei

config/users.json

ist nicht Bestandteil des Git-Repositories.

Vor dem ersten Start nach einem Deployment sicherstellen:

• Datei vorhanden
• gültiges JSON
• mindestens ein Benutzer vorhanden
• für den Service-Benutzer lesbar

Empfohlene Dateirechte:

sudo chown martin:www-data config/users.json
sudo chmod 640 config/users.json

Neue Benutzer werden ausschließlich mit folgendem Werkzeug verwaltet:

python3 scripts/manage_users.py

---

4. Build-Informationen prüfen

Falls erforderlich:

./scripts/update_build_info.sh

Anschließend kontrollieren:

cat build_info.json

Die Build-Version wird unter anderem für den What's New-Dialog verwendet.

---

5. RollCalc neu starten

sudo systemctl restart rollcalc.service
sudo systemctl status rollcalc.service --no-pager

---

6. Smoke-Test

Nach jedem Deployment mindestens folgende Punkte prüfen:

• Login funktioniert
• Roll Calculator öffnet
• User Manual erreichbar
• Recent Changes erreichbar
• What's New erscheint bei neuer Version
• Beispielberechnung durchführen
• Load Optimizer funktioniert

---

Fehlerdiagnose

Service-Status

sudo systemctl status rollcalc.service --no-pager

Journal anzeigen

sudo journalctl -u rollcalc.service -n 100 --no-pager

Benutzerdatei prüfen

ls -l config/users.json

sudo -u www-data test -r config/users.json && echo "users.json readable"

---

Benutzerverwaltung

Die Benutzerverwaltung erfolgt ausschließlich über:

python3 scripts/manage_users.py

Die Datei

config/users.json

wird nicht versioniert und muss auf jedem Zielsystem separat gepflegt werden.

Die Datei darf niemals in das Git-Repository eingecheckt werden.

---

Rollback

Vor jedem Deployment empfiehlt es sich, den aktuellen Commit zu notieren:

git rev-parse HEAD

Rollback auf einen früheren Stand:

git switch develop/v0.4
git reset --hard <Commit-ID>

sudo systemctl restart rollcalc.service

---

Wartungshinweise

• Neue Python-Abhängigkeiten immer über die virtuelle Umgebung installieren.
• config/users.json regelmäßig sichern. cp config/users.json backups/users_$(date +%F).json
• build_info.json vor einem Release aktualisieren.
• Nach Änderungen an der Authentifizierung die Benutzerverwaltung testen.
• Nach Änderungen am Help-System User Manual und Recent Changes prüfen.
• Nach Änderungen an Berechnungen mindestens einen vollständigen Rechentest durchführen.