From 8d6d85bd2ef8d9451538d0e4dae816fadcdbdd05 Mon Sep 17 00:00:00 2001 From: Martin Tazl Date: Tue, 28 Jul 2026 15:41:22 +0200 Subject: [PATCH] docs: add PDF export for user manual 2 --- docs/DEPLOYMENT_GUIDE.md | 384 +++++++++++++++++---------------------- 1 file changed, 165 insertions(+), 219 deletions(-) diff --git a/docs/DEPLOYMENT_GUIDE.md b/docs/DEPLOYMENT_GUIDE.md index 5b944b8..5a83bae 100644 --- a/docs/DEPLOYMENT_GUIDE.md +++ b/docs/DEPLOYMENT_GUIDE.md @@ -1,267 +1,213 @@ -# 🚀 RollCalc V14 + QoL Update - Deployment Guide +# Deployment Guide -## 📦 Archive Contents +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 ``` -rollcalc_v14_complete_final.tar.gz (18 KB) -rollcalc_files/ -├── app.py ← Flask Backend -├── service-worker.js ← Offline Support -├── config.json ← Forklift Rules -├── article-data.json ← Product Database (PLACEHOLDER) -│ -├── rollcalc_improvements.js ← V14: Article Selection -├── rollcalc_stddev_ranges.js ← QoL: Stddev Ranges -├── rollcalc_stddev_integration.js ← QoL: Integration -│ -├── deploy_rollcalc.py ← 🎯 DEPLOYMENT SCRIPT -│ -├── README.md ← Full Documentation -├── QUICKREF.md ← Quick Reference -├── INTEGRATION_GUIDE.html ← Step-by-Step Setup -├── FILE_STRUCTURE.md ← File Reference -├── DELIVERY_SUMMARY.md ← V14 Overview -├── QOL_UPDATE_SUMMARY.md ← QoL Overview -├── STDDEV_RANGES_DOCS.md ← Stddev Documentation -└── STDDEV_IMPLEMENTATION_CHECKLIST.md ← Implementation Checklist +- Python Virtual Environment + +```text +/opt/rollcalc-venv +``` + +- systemd-Service + +```text +rollcalc.service ``` --- -## 🎯 Quick Deployment (3 Steps) +# Deployment -### Step 1: Extract Archive +## 1. Repository aktualisieren ```bash -tar -xzf rollcalc_v14_complete_final.tar.gz -cd rollcalc_files/ +cd /var/www/html + +git fetch origin +git switch develop/v0.4 +git pull --ff-only origin develop/v0.4 ``` -### Step 2: Run Deployment Script +--- + +## 2. Python-Abhängigkeiten aktualisieren + +Neue Python-Abhängigkeiten werden ausschließlich in der virtuellen Umgebung installiert. ```bash -# Make executable (first time only) -chmod +x deploy_rollcalc.py - -# Run deployment -python3 deploy_rollcalc.py /path/to/your/flask/root/ - -# Example: -python3 deploy_rollcalc.py /home/user/rollcalc/ +sudo /opt/rollcalc-venv/bin/python \ + -m pip install -r requirements.txt ``` -### Step 3: Update Configuration +--- -Edit `app.py` (in your Flask root) and update passwords: +## 3. Benutzerdatei prüfen -```python -BETA_USERS = { - "beta": "CHANGE_THIS_PASSWORD", - "mtazl": "CHANGE_THIS_PASSWORD", - "cniehues": "CHANGE_THIS_PASSWORD", - # ... etc -} +Die Datei -ADMIN_USERS = { - "admin": "CHANGE_THIS_ADMIN_PASSWORD" -} +```text +config/users.json ``` -Then run: +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 -cd /path/to/your/flask/root/ -python app.py +sudo chown martin:www-data config/users.json +sudo chmod 640 config/users.json ``` -Open: **http://localhost:5000** - ---- - -## 📋 What the Deployment Script Does - -The `deploy_rollcalc.py` script automates everything: - -✅ Creates required directories -✅ Backs up existing files -✅ Deploys all files to correct locations -✅ Verifies Python dependencies -✅ Checks for default passwords -✅ Validates all files after deployment -✅ Prints clear next steps - -**No manual copying needed!** - ---- - -## ⚠️ Important: article-data.json - -The archive contains a **placeholder** for `article-data.json`. - -**You need to add your product data:** - -### Option A: Import from Existing System +Neue Benutzer werden ausschließlich mit folgendem Werkzeug verwaltet: ```bash -# If you already have article-data.json: -cp /path/to/your/article-data.json /path/to/flask/static/ -``` - -### Option B: Use Minimal Data for Testing - -The placeholder is already there - you can test the calculator without product data. - -### Option C: Generate from ERP - -Update the export script in your ERP system to create article-data.json format: - -```json -[ - { - "nr": "180005", - "name": "Bfix NSP 4000, 5,00 x 50 m", - "thickness": 6.228, - "thickness_stddev": 0.379, - "area_weight": 3899.02, - "area_weight_stddev": 133.24, - "core_type": 0.0, - ... - } -] +python3 scripts/manage_users.py ``` --- -## 🛠️ Manual Deployment (If Script Fails) +## 4. Build-Informationen prüfen -If the Python script doesn't work, deploy manually: +Falls erforderlich: ```bash -# Extract -tar -xzf rollcalc_v14_complete_final.tar.gz - -# Backend -cp rollcalc_files/app.py /path/to/flask/ - -# Static files -cp rollcalc_files/*.js /path/to/flask/static/ -cp rollcalc_files/*.json /path/to/flask/static/ - -# Documentation -mkdir -p /path/to/flask/docs -cp rollcalc_files/*.md /path/to/flask/docs/ -cp rollcalc_files/*.html /path/to/flask/docs/ - -# Run -cd /path/to/flask/ -python app.py +./scripts/update_build_info.sh ``` ---- - -## ✅ Verification Checklist - -After deployment, verify: - -- [ ] `app.py` in Flask root -- [ ] `service-worker.js` in `/static/` -- [ ] `rollcalc_improvements.js` in `/static/` -- [ ] `rollcalc_stddev_ranges.js` in `/static/` -- [ ] `rollcalc_stddev_integration.js` in `/static/` -- [ ] `article-data.json` in `/static/` (with real data) -- [ ] `config.json` in `/static/` -- [ ] `templates/roll_calculator.html` exists (add 2 script tags for StdDev) -- [ ] Passwords updated in `app.py` -- [ ] Server runs: `python app.py` -- [ ] Page loads: `http://localhost:5000` -- [ ] Login works (use credentials from `BETA_USERS`) - ---- - -## 🎨 HTML Integration (StdDev Ranges) - -If you want to use the **Standard Deviation Ranges** feature, add to your `roll_calculator.html` in the `` section: - -```html - - - - - - -``` - ---- - -## 📚 Documentation Files - -| File | Purpose | -|------|---------| -| `README.md` | Full technical documentation | -| `QUICKREF.md` | Quick reference card | -| `QOL_UPDATE_SUMMARY.md` | What's new in this update | -| `STDDEV_RANGES_DOCS.md` | How StdDev ranges work | -| `STDDEV_IMPLEMENTATION_CHECKLIST.md` | How to implement StdDev ranges | -| `INTEGRATION_GUIDE.html` | Original V14 setup guide | -| `FILE_STRUCTURE.md` | File reference | - -Read these **after deployment** to understand all features. - ---- - -## 🆘 Troubleshooting - -### "Deploy script fails: Missing dependencies" +Anschließend kontrollieren: ```bash -pip install flask flask-httpauth +cat build_info.json ``` -### "Page won't load at localhost:5000" - -1. Check Flask is running: `python app.py` -2. Check port 5000 is free -3. Check firewall allows localhost:5000 - -### "Login prompt appears but password doesn't work" - -1. Check `BETA_USERS` in `app.py` - use those credentials -2. Username: `mtazl`, Password: `rollcalc` (default) -3. Change to your custom passwords - -### "Article dropdown is empty" - -1. Check `article-data.json` exists in `/static/` -2. Check it has valid JSON format -3. Refresh browser (Ctrl+F5 or Cmd+Shift+R) -4. Check browser console (F12) for errors - -### "Service Worker not working" - -1. Clear browser cache (Ctrl+Shift+Delete) -2. Hard refresh (Ctrl+Shift+F5) -3. Check DevTools → Application → Service Workers +Die Build-Version wird unter anderem für den **What's New**-Dialog verwendet. --- -## 🚀 You're Ready! +## 5. RollCalc neu starten -That's it! The deployment script handles 90% of the work. - -**Questions?** Check the documentation files in `/docs/` - -**Issues?** Look in browser console (F12) for error messages - -**Success indicators:** -- ✅ Page loads at localhost:5000 -- ✅ Login prompt appears -- ✅ Article dropdown has data -- ✅ Calculations work -- ✅ Offline mode works (DevTools → Network → Offline) +```bash +sudo systemctl restart rollcalc.service +sudo systemctl status rollcalc.service --no-pager +``` --- -**Version:** 14.1 -**Date:** 2026-07-01 -**Status:** Production Ready ✅ +## 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 + +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. \ No newline at end of file