HUGGINGFACE_DEPLOYMENT.md

# 🤗 Hugging Face Spaces Deployment Guide

## Why Hugging Face Spaces?

✅ **FREE** hosting with your HF Pro account
✅ **Persistent storage** for database and AI models
✅ **Public URL** (e.g., `https://your-username-participatory-planner.hf.space`)
✅ **Auto-SSL** (HTTPS included)
✅ **Easy updates** via Git
✅ **No server management** needed
✅ **Pro perks**: Better hardware, faster model loading

---

## Deployment Steps

### Method 1: Web UI (Easiest - 5 minutes)

1. **Go to Hugging Face Spaces**
   - Visit: https://huggingface.co/new-space
   - Login with your HF Pro account

2. **Create New Space**
   - **Owner**: Your username
   - **Space name**: `participatory-planner` (or your choice)
   - **License**: MIT
   - **SDK**: Select **Docker**
   - **Hardware**:
     - Free tier: CPU Basic (2 vCPU, 16GB RAM) ✅ Sufficient
     - Pro upgrade: CPU Upgrade (4 vCPU, 32GB RAM) - Faster AI analysis
   - **Visibility**: Public or Private

3. **Upload Files**

   Click "Files" tab, then upload these files from your project:

   **Required files:**
   ```
   📄 Dockerfile (already configured for HF Spaces)
   📄 requirements.txt
   📄 app_hf.py
   📁 app/ (entire folder)
   📄 wsgi.py
   📄 .gitignore
   📄 README.md (the HF version)
   ```

   **Optional but recommended:**
   ```
   📄 .env (with your FLASK_SECRET_KEY)
   ```

4. **Configure Secrets** (Important!)

   Go to "Settings" → "Repository secrets"

   Add secret:
   - **Name**: `FLASK_SECRET_KEY`
   - **Value**: `8606a4f67a03c5579a6e73f47195549d446d1e55c9d41d783b36762fc4cd9d75`

5. **Wait for Build**
   - Hugging Face will automatically build and deploy
   - First build takes ~5-10 minutes (downloads AI model)
   - Watch the "Logs" tab for progress

6. **Access Your App!**
   - URL: `https://huggingface.co/spaces/YOUR_USERNAME/participatory-planner`
   - Or embedded: `https://YOUR_USERNAME-participatory-planner.hf.space`
   - Login: `<see-startup-logs-or-set-ADMIN_TOKEN>`

---

### Method 2: Git CLI (For developers)

1. **Initialize Git repo** (if not already):
   ```bash
   cd /home/thadillo/MyProjects/participatory_planner
   git init
   ```

2. **Add Hugging Face remote**:
   ```bash
   # Install git-lfs for large files
   git lfs install

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

3. **Prepare files**:
   ```bash
   # Make sure we're using HF-compatible Dockerfile
   cp Dockerfile.hf Dockerfile
   cp README_HF.md README.md
   ```

4. **Commit and push**:
   ```bash
   git add .
   git commit -m "Initial deployment to Hugging Face Spaces"
   git push hf main
   ```

5. **Set secrets** on HF Spaces web UI (Settings → Secrets)

---

## File Structure for HF Spaces

Your Space should have this structure:

```
participatory-planner/
├── Dockerfile              # HF Spaces configuration (port 7860)
├── README.md              # Space description (with YAML header)
├── requirements.txt       # Python dependencies
├── app_hf.py             # HF Spaces entry point
├── wsgi.py               # WSGI app
├── .gitignore            # Ignore patterns
├── app/                  # Main application
│   ├── __init__.py
│   ├── analyzer.py
│   ├── models/
│   ├── routes/
│   └── templates/
└── instance/             # Created at runtime (database)
```

---

## Configuration Details

### Dockerfile Port
Hugging Face Spaces requires **port 7860**. This is already configured in `Dockerfile.hf` and `app_hf.py`.

### README.md Header
The HF version has special YAML metadata at the top:
```yaml
---
title: Participatory Planning Application
emoji: 🏙️
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
license: mit
---
```

This configures how your Space appears on HF.

### Environment Variables
Set these in Space Settings → Repository secrets:
- `FLASK_SECRET_KEY`: Your secure secret key (already generated)
- `FLASK_ENV`: Set to `production`

### Persistent Storage
- Database stored in `/app/instance/` (persists between restarts)
- AI model cached in `/root/.cache/huggingface/` (persists)
- First run downloads ~1.5GB model (one-time)

---

## Advantages of HF Pro

With your **Hugging Face Pro** account, you get:

✅ **Better hardware**:
- CPU Upgrade: 4 vCPU, 32GB RAM
- GPU options available (T4, A10G, A100)
- Faster AI analysis

✅ **Private Spaces**:
- Keep your planning sessions confidential
- Password protection available

✅ **Persistent storage**:
- 50GB for Pro (vs 5GB free)
- Database and models persist

✅ **Custom domains**:
- Use your own domain name
- Better branding

✅ **No sleep**:
- Space stays always-on
- No cold starts

✅ **Priority support**:
- Faster builds
- Better reliability

---

## Cost Comparison

| Platform | Free Tier | Pro Cost | Our Recommendation |
|----------|-----------|----------|-------------------|
| **Hugging Face Pro** | ✅ Included | $9/mo (you have!) | ⭐ **BEST** |
| Heroku | ❌ None | $7/mo | Limited resources |
| DigitalOcean | ❌ None | $12/mo | Good alternative |
| AWS EC2 | ✅ 12 months | ~$15/mo | Complex setup |
| Railway | ✅ $5 credit | $5/mo | Good for prototypes |
| Render | ✅ 750 hrs/mo | $7/mo | Good alternative |

**Winner**: Hugging Face Spaces with your Pro account = **FREE + BEST**

---

## GPU Acceleration (Optional)

Your app works fine on CPU, but for **very large sessions** (500+ submissions), you can enable GPU:

1. Go to Space Settings → Hardware
2. Select GPU (T4 is cheapest)
3. Update `app/analyzer.py`:
   ```python
   # Change device from -1 (CPU) to 0 (GPU)
   self.classifier = pipeline("zero-shot-classification",
                              model=self.model_name,
                              device=0)  # Use GPU
   ```

**Note**: GPU costs extra (~$0.60/hr with Pro discount). Only enable if needed.

---

## Updating Your Space

### Via Web UI:
1. Go to your Space → Files tab
2. Click on file to edit
3. Make changes and commit

### Via Git:
```bash
git add .
git commit -m "Update feature X"
git push hf main
```

Space rebuilds automatically on push.

---

## Monitoring & Logs

### View Logs:
1. Go to your Space
2. Click "Logs" tab
3. See real-time application logs

### Check Status:
- Green badge = Running
- Yellow badge = Building
- Red badge = Error

### Metrics (Pro):
- View CPU/RAM usage
- Monitor request counts
- Track uptime

---

## Troubleshooting

### Build fails with "out of memory"
**Solution**: Upgrade to CPU Upgrade hardware (Settings → Hardware)

### AI model download times out
**Solution**: First build takes 10+ minutes. Be patient. Model caches after first run.

### Database resets on restart
**Solution**: Ensure `/app/instance/` is in a persistent volume. Check Dockerfile:
```dockerfile
RUN mkdir -p instance
```

### Port errors
**Solution**: HF Spaces requires port 7860. Verify `app_hf.py` uses this port.

### Can't access Space
**Solution**: Check Space visibility in Settings. Set to Public or add collaborators.

---

## Advanced: Custom Domain

With HF Pro, you can use your own domain:

1. **Go to Settings** → Custom domains
2. **Add domain**: `planning.yourdomain.com`
3. **Configure DNS**:
   ```
   CNAME planning -> YOUR_USERNAME-participatory-planner.hf.space
   ```
4. **Wait for verification** (5-30 minutes)
5. **Access**: `https://planning.yourdomain.com`

SSL certificate automatically provisioned!

---

## Backup Strategy

Since HF Spaces has persistent storage, you should still backup:

### Automatic Backups:
Use the **Export JSON** feature weekly:
1. Login as admin
2. Click "Save Session" (top nav)
3. Downloads complete backup
4. Store in cloud (Google Drive, Dropbox, etc.)

### Manual Database Backup:
Access Space terminal (if enabled) and copy `/app/instance/app.db`

---

## Security Best Practices

1. **Change admin token**:
   - Edit `app/models/models.py`
   - Change `<see-startup-logs-or-set-ADMIN_TOKEN>` to secure token
   - Redeploy

2. **Use secrets** for sensitive data:
   - Never commit `.env` with real keys
   - Use HF Secrets for configuration

3. **Enable authentication** (optional):
   - HF Spaces can add login wall
   - Settings → Enable authentication

4. **Make Space private** (for confidential sessions):
   - Settings → Visibility → Private
   - Only invited users can access

---

## Next Steps After Deployment

1. **Share your Space**:
   ```
   🏙️ Participatory Planning Platform
   https://huggingface.co/spaces/YOUR_USERNAME/participatory-planner

   Admin: ADMIN123
   ```

2. **Customize branding**:
   - Edit README.md header (emoji, colors)
   - Update templates in `app/templates/`

3. **Monitor usage**:
   - Check Logs regularly
   - Export data weekly
   - Watch for errors

4. **Scale if needed**:
   - Upgrade hardware for large sessions
   - Enable GPU for faster analysis
   - Add custom domain

---

## Support

- **HF Spaces Docs**: https://huggingface.co/docs/hub/spaces
- **HF Community**: https://discuss.huggingface.co/
- **Your App Logs**: Space → Logs tab

---

## Summary

✅ **You have Hugging Face Pro** = Perfect fit!

**Deploy in 3 steps:**
1. Create Space on huggingface.co/new-space (SDK: Docker)
2. Upload project files
3. Access at `https://YOUR_USERNAME-participatory-planner.hf.space`

**Total cost**: $0 (included in your HF Pro)

**Time to deploy**: 5-10 minutes

**Maintenance**: Zero (auto-managed)

🎉 **This is the best free deployment option for your demo!**