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

   cd /home/thadillo/MyProjects/participatory_planner
   git init
   

2. Add Hugging Face remote:

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

   # Make sure we're using HF-compatible Dockerfile
   cp Dockerfile.hf Dockerfile
   cp README_HF.md README.md
   

4. Commit and push:

   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:

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:

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!