HF_DEPLOYMENT_CHECKLIST.md

✅ Hugging Face Spaces Deployment Checklist

Pre-Deployment (Local Setup)

1. Database Preparation

• Create external PostgreSQL database (Render/Neon)
• Test database connection locally
• Run database migrations (if any)
• Create initial admin user (optional)

2. Code Preparation

• Review Dockerfile (port 7860, user permissions)
• Verify requirements.txt has all dependencies
• Check database.py hybrid connection logic
• Test application locally with Docker
• Generate strong SECRET_KEY

3. Files to Push

• Dockerfile (CRITICAL)
• requirements.txt
• main.py
• app/ directory (all modules)
• README_HF_SPACE.md (rename to README.md)
• .dockerignore

4. Files to EXCLUDE

• .env files (secrets)
• env/ or venv/ directories
• __pycache__/ directories
• Local .db files
• app/static/uploads/ temporary files

---

Hugging Face Spaces Setup

1. Create New Space

• Go to https://huggingface.co/new-space
• Choose a memorable Space name
• Select Docker SDK
• Choose CPU Basic (16GB RAM - Free Tier)
• Set visibility (Public/Private)
• Click Create Space

2. Configure Environment Variables

Navigate to Settings → Repository Secrets

Required Secrets:

• Add DATABASE_URL

  postgresql://user:pass@host:port/database
  

• Add SECRET_KEY

  (generated random string, 32+ chars)
  

Verify:

• Secrets show as *** (hidden)
• No typos in variable names
• DATABASE_URL starts with postgresql://

---

Deployment

1. Push Code to HF Space

# Clone your Space repository
git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE
cd YOUR_SPACE

# Copy project files
# (Exclude env/, __pycache__, .db files)

# IMPORTANT: Rename README
cp README_HF_SPACE.md README.md

# Initialize git (if needed)
git init
git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE

# Commit and push
git add .
git commit -m "Initial deployment to Hugging Face Spaces"
git push -u origin main

2. Monitor Build

• Go to your Space URL
• Click Logs tab
• Watch Docker build process
• Wait for "Running on http://0.0.0.0:7860" message
• Build time: ~5-10 minutes

3. Expected Build Stages

✅ Building Docker image...
✅ Installing dependencies from requirements.txt...
✅ Downloading PyTorch & Transformers (~2GB)...
✅ Creating user 'user' (UID 1000)...
✅ Setting permissions...
✅ Starting uvicorn server...
✅ Application running on port 7860

---

Post-Deployment Verification

1. Check Application Status

• Space shows "Running" status (green)
• No errors in Logs tab
• Access Space URL (opens app)

2. Test Database Connection

Expected log message:

🚀 Production Mode: Using PostgreSQL

If you see this instead:

🔧 Development Mode: Using SQLite

→ DATABASE_URL is missing or incorrect

3. Test Core Functionality

• Access /docs (Swagger UI loads)
• Register a new user
• Login successfully
• Access dashboard
• Make a single prediction
• Upload CSV for batch prediction
• View prediction history
• Word cloud generates
• Charts display correctly

4. Security Verification

• Cannot access protected routes without JWT
• Passwords are hashed (check database)
• JWT tokens expire after 24 hours
• HTTPS is enabled (HF provides this)

---

Troubleshooting

Issue: Build Failed

Check:

• Dockerfile syntax errors
• Missing dependencies in requirements.txt
• Python version compatibility
• Check Logs for specific error

Issue: "Application startup failed"

Check:

• DATABASE_URL is set correctly
• Database is accessible (not firewalled)
• SECRET_KEY is set
• Port 7860 is used in CMD

Issue: "502 Bad Gateway"

Check:

• App is still starting (wait 2-3 min)
• Heavy model loading in progress
• Check Logs for crash/errors

Issue: Database Connection Error

Check:

• DATABASE_URL format is correct
• Database host is reachable
• Username/password are correct
• Database allows external connections

Issue: JWT Token Invalid

Check:

• SECRET_KEY is set correctly
• SECRET_KEY hasn't changed
• Token hasn't expired (24h)
• Clear browser localStorage

---

Maintenance

Regular Tasks

• Monitor Space usage (CPU/Memory)
• Check application logs weekly
• Rotate SECRET_KEY every 90 days
• Backup PostgreSQL database regularly
• Update dependencies monthly

Updating the App

# Make changes locally
git add .
git commit -m "Update: description"
git push

# HF will automatically rebuild
# Monitor Logs tab for build status

Scaling Considerations

If you exceed Free Tier limits:

• Upgrade to Pro Space (better hardware)
• Consider upgrading database plan
• Implement caching (Redis)
• Optimize model loading

---

Performance Optimization

For Heavy Models

• Use model quantization (reduces size)
• Cache model in memory (don't reload)
• Use CPU inference (GPU costs more)
• Implement request queuing

For High Traffic

• Add rate limiting
• Implement Redis caching
• Use CDN for static files
• Optimize database queries
• Add connection pooling

---

Security Hardening

Production Checklist

• Use strong SECRET_KEY (32+ chars)
• Enable DATABASE SSL (sslmode=require)
• Implement rate limiting
• Add CORS restrictions
• Log all authentication attempts
• Implement password strength requirements
• Add 2FA (future enhancement)
• Regular security audits

---

Rollback Plan

If deployment fails:

Option 1: Revert Git Commit

git revert HEAD
git push

Option 2: Delete and Recreate Space

1. Delete current Space
2. Create new Space with same name
3. Re-add environment variables
4. Push working version

Option 3: Use Previous Docker Image

HF keeps previous builds for Pro users

---

Success Criteria

Deployment is successful when:

• ✅ Space status is "Running"
• ✅ No errors in Logs
• ✅ PostgreSQL connection established
• ✅ All API endpoints respond
• ✅ Frontend loads correctly
• ✅ Users can register and login
• ✅ Predictions work (single + batch)
• ✅ Visualizations generate
• ✅ JWT authentication works

---

Support Resources

• 📖 Hugging Face Spaces Docs
• 📖 Docker SDK Guide
• 📖 FastAPI Documentation
• 📖 SQLAlchemy Docs
• 💬 HF Community Forum

---

Last Updated: December 2025 Version: 1.0.0