HF_DEPLOYMENT_CHECKLIST.md

🚀 Hugging Face Deployment Checklist

✅ Pre-Deployment Checklist

1. Files Ready

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

2. Configuration Verified

• Port 7860 configured in Dockerfile.hf and app_hf.py
• Database path uses environment variable (DATABASE_PATH=/data/app.db)
• HuggingFace cache configured (/data/.cache/huggingface)
• Session cookies configured for iframe embedding
• Health check endpoint configured
• 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:

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

git lfs install

Step 2: Create Space via CLI

# 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

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

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

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:

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