RollCalcPython/docs/DEPLOYMENT_GUIDE.md

# 🚀 RollCalc V14 + QoL Update - Deployment Guide

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

```bash
tar -xzf rollcalc_v14_complete_final.tar.gz
cd rollcalc_files/
```

### Step 2: Run Deployment Script

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

### Step 3: Update Configuration

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

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

ADMIN_USERS = {
    "admin": "CHANGE_THIS_ADMIN_PASSWORD"
}
```

Then run:

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

```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,
    ...
  }
]
```

---

## 🛠️ Manual Deployment (If Script Fails)

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

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

---

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