RollCalcPython/docs/DEPLOYMENT_GUIDE.md

🚀 RollCalc V14 + QoL Update - Deployment Guide

Current repository note: direct roll-diameter calculations are generated server-side by roll_calculation.py, and PDF reports are rendered by pdf_report.py. Deploy both beside app.py, install the unchanged requirements.txt, and ensure nginx forwards authenticated POST /api/calculations/roll, POST /api/calculations/roll/modify, and POST /api/reports/roll-calculation.pdf requests to Flask. No browser, system PDF/font package, or additional Python dependency is required; the generated report is one A4 page under normal calculator conditions.

📦 Archive Contents

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

---

🎯 Quick Deployment (3 Steps)

Step 1: Extract Archive

tar -xzf rollcalc_v14_complete_final.tar.gz
cd rollcalc_files/

Step 2: Run Deployment Script

# 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/

Step 3: Update Configuration

Edit app.py (in your Flask root) and update passwords:

BETA_USERS = {
    "beta": "CHANGE_THIS_PASSWORD",
    "mtazl": "CHANGE_THIS_PASSWORD",
    "cniehues": "CHANGE_THIS_PASSWORD",
    # ... etc
}

ADMIN_USERS = {
    "admin": "CHANGE_THIS_ADMIN_PASSWORD"
}

Then run:

cd /path/to/your/flask/root/
python app.py

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

# 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:

[
  {
    "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)

If the Python script doesn't work, deploy manually:

# 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

---

✅ 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:

<!-- 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"

pip install flask flask-httpauth

"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

---

🚀 You're Ready!

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)

---

Version: 14.1
Date: 2026-07-01
Status: Production Ready ✅