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/
|
||||
├── 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 `<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"
|
||||
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 <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