# 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

```text
/var/www/html
```

- Python Virtual Environment

```text
/opt/rollcalc-venv
```

- systemd-Service

```text
rollcalc.service
```

---

# Deployment

## 1. Repository aktualisieren

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

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

---

## 3. Benutzerdatei prüfen

Die Datei

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

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

Neue Benutzer werden ausschließlich mit folgendem Werkzeug verwaltet:

```bash
python3 scripts/manage_users.py
```

---

## 4. Build-Informationen prüfen

Falls erforderlich:

```bash
./scripts/update_build_info.sh
```

Anschließend kontrollieren:

```bash
cat build_info.json
```

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

---

## 5. RollCalc neu starten

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

```bash
sudo systemctl status rollcalc.service --no-pager
```

## Journal anzeigen

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

## Benutzerdatei prüfen

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

```bash
python3 scripts/manage_users.py
```

Die Datei

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

```bash
git rev-parse HEAD
```

Rollback auf einen früheren Stand:

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