HF_DEPLOYMENT_CHECKLIST.md

# 🚀 Hugging Face Deployment Checklist

## ✅ Pre-Deployment Checklist

### 1. Files Ready
- [x] `Dockerfile.hf` - HF-compatible Docker configuration
- [x] `app_hf.py` - HF Spaces entry point (port 7860)
- [x] `README_HF.md` - Space description with YAML metadata
- [x] `requirements.txt` - All dependencies included
- [x] `app/` directory - Complete application code
- [x] `.gitignore` - Ignore patterns configured
- [x] `wsgi.py` - WSGI application wrapper

### 2. Configuration Verified
- [x] Port 7860 configured in Dockerfile.hf and app_hf.py
- [x] Database path uses environment variable (DATABASE_PATH=/data/app.db)
- [x] HuggingFace cache configured (/data/.cache/huggingface)
- [x] Session cookies configured for iframe embedding
- [x] Health check endpoint configured
- [x] Models directory configured (models/finetuned/)

### 3. Security
- [ ] **IMPORTANT**: Update FLASK_SECRET_KEY in HF Secrets
  - Use this secure key: `9fd11d101e36efbd3a7893f56d604b860403d247633547586c41453118e69b00`
- [ ] Consider changing ADMIN123 token to something more secure
- [ ] Review .hfignore to exclude sensitive files

---

## 🎯 Deployment Steps

### Option A: Web UI (Recommended - 5 minutes)

#### Step 1: Create Space
1. Go to https://huggingface.co/new-space
2. Login with your HF Pro account
3. Fill in:
   - **Space name**: `participatory-planner`
   - **License**: MIT
   - **SDK**: Docker ⚠️ IMPORTANT
   - **Hardware**: CPU Basic (or CPU Upgrade for Pro)
   - **Visibility**: Public or Private

#### Step 2: Prepare Files for Upload
Run this command to copy HF-specific files:
```bash
cd /home/thadillo/MyProjects/participatory_planner

# Copy HF-specific files to root
cp Dockerfile.hf Dockerfile
cp README_HF.md README.md
```

#### Step 3: Upload Files via Web UI
Upload these files/folders to your Space:
- ✅ `Dockerfile` (the HF version)
- ✅ `README.md` (the HF version with YAML header)
- ✅ `requirements.txt`
- ✅ `app_hf.py`
- ✅ `wsgi.py`
- ✅ `app/` (entire folder with all subfolders)
- ✅ `.gitignore`

**DO NOT upload:**
- ❌ `venv/` (Python virtual environment)
- ❌ `instance/` (local database)
- ❌ `models/finetuned/` (will be created on HF)
- ❌ `.git/` (Git history)
- ❌ `__pycache__/` (Python cache)

#### Step 4: Configure Secrets
1. Go to your Space → Settings → Repository secrets
2. Click "Add a secret"
3. Add:
   - **Name**: `FLASK_SECRET_KEY`
   - **Value**: `9fd11d101e36efbd3a7893f56d604b860403d247633547586c41453118e69b00`
4. (Optional) Add:
   - **Name**: `FLASK_ENV`
   - **Value**: `production`

#### Step 5: Wait for Build
1. Go to "Logs" tab
2. Watch the build process (5-10 minutes first time)
3. Look for: `Running on http://0.0.0.0:7860`
4. Space will show "Building" → "Running"

#### Step 6: Access & Test
1. Visit: `https://huggingface.co/spaces/YOUR_USERNAME/participatory-planner`
2. Login with: `ADMIN123`
3. Test all features:
   - [ ] Registration page loads
   - [ ] Can create tokens
   - [ ] Can submit contributions
   - [ ] AI analysis works
   - [ ] Dashboard displays correctly
   - [ ] Map visualization works
   - [ ] Training panel accessible
   - [ ] Export/Import works

---

### Option B: Git CLI (For Advanced Users)

#### Step 1: Install Git LFS
```bash
git lfs install
```

#### Step 2: Create Space via CLI
```bash
# Install HF CLI
pip install huggingface_hub

# Login to HF
huggingface-cli login

# Create space (replace YOUR_USERNAME)
huggingface-cli repo create participatory-planner --type space --space_sdk docker
```

#### Step 3: Prepare Repository
```bash
cd /home/thadillo/MyProjects/participatory_planner

# Copy HF-specific files
cp Dockerfile.hf Dockerfile
cp README_HF.md README.md

# Add HF remote
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/participatory-planner
```

#### Step 4: Commit and Push
```bash
# Make sure .hfignore is in place
git add .
git commit -m "🚀 Initial deployment to Hugging Face Spaces"
git push hf main
```

#### Step 5: Configure secrets via Web UI
(Same as Option A, Step 4)

---

## 📋 Post-Deployment Verification

### Essential Tests
- [ ] Space builds successfully (check Logs)
- [ ] App is accessible at Space URL
- [ ] Admin login works (ADMIN123)
- [ ] Database persists between restarts
- [ ] AI model loads successfully
- [ ] File uploads work
- [ ] Map loads correctly

### Performance Checks
- [ ] First load time < 3 seconds (after warm-up)
- [ ] AI analysis completes in < 5 seconds
- [ ] No memory errors in logs
- [ ] Model caching works (subsequent loads faster)

### Security Checks
- [ ] FLASK_SECRET_KEY is set in Secrets (not in code)
- [ ] No sensitive data in logs
- [ ] HTTPS works correctly
- [ ] Session cookies work in iframe

---

## 🔧 Troubleshooting

### Build Fails
**Error**: "Out of memory during build"
- **Solution**: Upgrade to CPU Upgrade hardware in Settings

**Error**: "Port 7860 not responding"
- **Solution**: Verify Dockerfile exposes 7860 and app_hf.py uses it

### Runtime Issues
**Error**: "Database locked" or "Database resets"
- **Solution**: Verify DATABASE_PATH=/data/app.db in Dockerfile

**Error**: "Model download timeout"
- **Solution**: First download takes 10+ minutes. Be patient. Check Logs.

**Error**: "Can't access Space"
- **Solution**: Check Space visibility (Settings). Set to Public.

### AI Model Issues
**Error**: "Transformers error on first run"
- **Solution**: Models download on first use. Check HF_HOME=/data/.cache

**Error**: "CUDA/GPU errors"
- **Solution**: App uses CPU by default. Don't select GPU hardware unless needed.

---

## 📊 Monitoring

### Daily Checks
- View Logs tab for errors
- Check Space status badge (green = good)
- Verify database size (Settings → Storage)

### Weekly Maintenance
- Export data backup via admin panel
- Review error logs
- Check model storage size
- Update dependencies if needed

---

## 🔄 Updates & Rollbacks

### To Update Your Space
Via Git:
```bash
git add .
git commit -m "Update: description of changes"
git push hf main
```

Via Web UI:
1. Go to Files tab
2. Edit files directly
3. Commit changes

### To Rollback
1. Go to Files → Commits
2. Find last working commit
3. Click "Revert to this commit"

---

## 💡 Optimization Tips

### For Better Performance
- Enable CPU Upgrade (4 vCPU, 32GB RAM) - Free with Pro!
- Use model presets (DeBERTa-v3-small recommended)
- Set persistent storage for model cache

### For Production Use
1. Change admin token from ADMIN123
2. Enable Space authentication (Settings)
3. Set up custom domain (Pro feature)
4. Enable always-on (Pro feature)
5. Set up monitoring alerts

---

## 🎉 Success Criteria

Your deployment is successful when:
- ✅ Space status shows "Running" (green badge)
- ✅ No errors in Logs for 5 minutes
- ✅ Admin login works
- ✅ AI analysis completes successfully
- ✅ Data persists after refresh
- ✅ All features work as in local development

---

## 📞 Support Resources

- **HF Spaces Docs**: https://huggingface.co/docs/hub/spaces
- **HF Discord**: https://hf.co/join/discord
- **App Logs**: Your Space → Logs tab
- **HF Status**: https://status.huggingface.co

---

## 🔐 Important Security Notes

**CRITICAL - Before going public:**

1. **Change Admin Token** in `app/models/models.py`:
   ```python
   if not Token.query.filter_by(token='YOUR_SECURE_TOKEN').first():
       admin_token = Token(token='YOUR_SECURE_TOKEN', type='admin', ...)
   ```

2. **Use HF Secrets** (never commit secrets):
   - FLASK_SECRET_KEY (already set)
   - Any API keys
   - Database credentials (if using external DB)

3. **Consider Space Authentication**:
   - Settings → Enable authentication
   - Require HF login to access

4. **For Confidential Sessions**:
   - Set Space to Private
   - Use password protection
   - Regular data backups

---

## 📝 Final Notes

**Estimated Deployment Time**: 10-15 minutes (first time)

**Resources Used** (with HF Pro):
- Storage: ~2GB (model cache + database)
- RAM: ~1-2GB during inference
- CPU: 2-4 cores recommended

**Cost**: $0 (included in HF Pro subscription) 🎉

**Next Step**: Click "Create Space" on huggingface.co/new-space and follow the checklist above!

---

**Good luck with your deployment! 🚀**