docs: add PDF export for user manual 2
This commit is contained in:
+165
-219
@@ -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/
|
- Python Virtual Environment
|
||||||
├── app.py ← Flask Backend
|
|
||||||
├── service-worker.js ← Offline Support
|
```text
|
||||||
├── config.json ← Forklift Rules
|
/opt/rollcalc-venv
|
||||||
├── article-data.json ← Product Database (PLACEHOLDER)
|
```
|
||||||
│
|
|
||||||
├── rollcalc_improvements.js ← V14: Article Selection
|
- systemd-Service
|
||||||
├── rollcalc_stddev_ranges.js ← QoL: Stddev Ranges
|
|
||||||
├── rollcalc_stddev_integration.js ← QoL: Integration
|
```text
|
||||||
│
|
rollcalc.service
|
||||||
├── 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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🎯 Quick Deployment (3 Steps)
|
# Deployment
|
||||||
|
|
||||||
### Step 1: Extract Archive
|
## 1. Repository aktualisieren
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
tar -xzf rollcalc_v14_complete_final.tar.gz
|
cd /var/www/html
|
||||||
cd rollcalc_files/
|
|
||||||
|
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
|
```bash
|
||||||
# Make executable (first time only)
|
sudo /opt/rollcalc-venv/bin/python \
|
||||||
chmod +x deploy_rollcalc.py
|
-m pip install -r requirements.txt
|
||||||
|
|
||||||
# Run deployment
|
|
||||||
python3 deploy_rollcalc.py /path/to/your/flask/root/
|
|
||||||
|
|
||||||
# Example:
|
|
||||||
python3 deploy_rollcalc.py /home/user/rollcalc/
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Step 3: Update Configuration
|
---
|
||||||
|
|
||||||
Edit `app.py` (in your Flask root) and update passwords:
|
## 3. Benutzerdatei prüfen
|
||||||
|
|
||||||
```python
|
Die Datei
|
||||||
BETA_USERS = {
|
|
||||||
"beta": "CHANGE_THIS_PASSWORD",
|
|
||||||
"mtazl": "CHANGE_THIS_PASSWORD",
|
|
||||||
"cniehues": "CHANGE_THIS_PASSWORD",
|
|
||||||
# ... etc
|
|
||||||
}
|
|
||||||
|
|
||||||
ADMIN_USERS = {
|
```text
|
||||||
"admin": "CHANGE_THIS_ADMIN_PASSWORD"
|
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
|
```bash
|
||||||
cd /path/to/your/flask/root/
|
sudo chown martin:www-data config/users.json
|
||||||
python app.py
|
sudo chmod 640 config/users.json
|
||||||
```
|
```
|
||||||
|
|
||||||
Open: **http://localhost:5000**
|
Neue Benutzer werden ausschließlich mit folgendem Werkzeug verwaltet:
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📋 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
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# If you already have article-data.json:
|
python3 scripts/manage_users.py
|
||||||
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,
|
|
||||||
...
|
|
||||||
}
|
|
||||||
]
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🛠️ Manual Deployment (If Script Fails)
|
## 4. Build-Informationen prüfen
|
||||||
|
|
||||||
If the Python script doesn't work, deploy manually:
|
Falls erforderlich:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Extract
|
./scripts/update_build_info.sh
|
||||||
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
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
Anschließend kontrollieren:
|
||||||
|
|
||||||
## ✅ 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 `<head>` section:
|
|
||||||
|
|
||||||
```html
|
|
||||||
<!-- Add these two lines: -->
|
|
||||||
<script src="/static/rollcalc-stddev-ranges.js"></script>
|
|
||||||
<script src="/static/rollcalc-stddev-integration.js"></script>
|
|
||||||
|
|
||||||
<!-- Also add this to your Direct Calc form: -->
|
|
||||||
<!-- (Details in STDDEV_IMPLEMENTATION_CHECKLIST.md) -->
|
|
||||||
```
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📚 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"
|
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
pip install flask flask-httpauth
|
cat build_info.json
|
||||||
```
|
```
|
||||||
|
|
||||||
### "Page won't load at localhost:5000"
|
Die Build-Version wird unter anderem für den **What's New**-Dialog verwendet.
|
||||||
|
|
||||||
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
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 🚀 You're Ready!
|
## 5. RollCalc neu starten
|
||||||
|
|
||||||
That's it! The deployment script handles 90% of the work.
|
```bash
|
||||||
|
sudo systemctl restart rollcalc.service
|
||||||
**Questions?** Check the documentation files in `/docs/`
|
sudo systemctl status rollcalc.service --no-pager
|
||||||
|
```
|
||||||
**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)
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**Version:** 14.1
|
## 6. Smoke-Test
|
||||||
**Date:** 2026-07-01
|
|
||||||
**Status:** Production Ready ✅
|
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.
|
||||||
Reference in New Issue
Block a user