docs/dev/spec/HUGGINGFACE_DEPLOYMENT.md

Deploying SwiftOps Backend to Hugging Face Spaces

🚀 Quick Deployment Guide

Prerequisites

• Hugging Face account
• Supabase account (for PostgreSQL database)
• Redis instance (Upstash, Redis Cloud, or similar)

---

📋 Step-by-Step Deployment

1. Create a New Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Configure:
   • Name: swiftops-backend
   • License: MIT
   • SDK: Docker
   • Hardware: CPU Basic (or upgrade as needed)

2. Set Up External Services

A. Supabase (PostgreSQL Database)

1. Create project at https://supabase.com
2. Get connection string from Settings → Database
3. Format: postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres

B. Redis (Upstash or Redis Cloud)

1. Create Redis instance at https://upstash.com or https://redis.com
2. Get connection URL
3. Format: redis://default:[PASSWORD]@[HOST]:6379

3. Configure Environment Variables

In your Hugging Face Space settings, add these secrets:

# Required
DATABASE_URL=postgresql://postgres:[PASSWORD]@[HOST]:5432/postgres
SUPABASE_URL=https://[PROJECT].supabase.co
SUPABASE_KEY=[YOUR_ANON_KEY]
SUPABASE_SERVICE_KEY=[YOUR_SERVICE_KEY]
SECRET_KEY=[GENERATE_WITH: openssl rand -hex 32]
REDIS_URL=redis://default:[PASSWORD]@[HOST]:6379
CELERY_BROKER_URL=redis://default:[PASSWORD]@[HOST]:6379
CELERY_RESULT_BACKEND=redis://default:[PASSWORD]@[HOST]:6379

# Optional (for production features)
CLOUDINARY_CLOUD_NAME=[YOUR_CLOUD_NAME]
CLOUDINARY_API_KEY=[YOUR_API_KEY]
CLOUDINARY_API_SECRET=[YOUR_API_SECRET]
RESEND_API_KEY=[YOUR_RESEND_KEY]
GOOGLE_MAPS_API_KEY=[YOUR_GOOGLE_MAPS_KEY]
SENTRY_DSN=[YOUR_SENTRY_DSN]

# Application Settings
ENVIRONMENT=production
DEBUG=False

4. Push Code to Hugging Face

Option A: Using Git

# Add Hugging Face remote
git remote add hf https://huggingface.co/spaces/[YOUR_USERNAME]/swiftops-backend

# Push to Hugging Face
git push hf main

Option B: Using Hugging Face Hub

# Install huggingface_hub
pip install huggingface_hub

# Login
huggingface-cli login

# Upload repository
huggingface-cli upload [YOUR_USERNAME]/swiftops-backend . --repo-type=space

5. Verify Deployment

1. Wait for Docker build to complete (5-10 minutes)
2. Check build logs in Space settings
3. Visit your Space URL: https://huggingface.co/spaces/[YOUR_USERNAME]/swiftops-backend
4. Test endpoints:
   • Health check: https://[YOUR_SPACE].hf.space/health
   • API docs: https://[YOUR_SPACE].hf.space/api/docs

---

🔧 Important Configuration Changes

1. Port Configuration

Hugging Face Spaces uses port 7860 by default. The Dockerfile has been updated:

EXPOSE 7860
CMD uvicorn src.app.main:app --host 0.0.0.0 --port 7860

2. Database Migrations

Migrations run automatically on startup:

CMD alembic upgrade head && uvicorn src.app.main:app --host 0.0.0.0 --port 7860

3. Files Included in Deployment

Deployed:

• ✅ src/ - Application code
• ✅ alembic/ - Database migrations
• ✅ alembic.ini - Migration config
• ✅ requirements.txt - Dependencies
• ✅ Dockerfile - Container definition
• ✅ README.md - Space description

Not Deployed (via .dockerignore):

• ❌ tests/ - Test suite
• ❌ scripts/ - Utility scripts
• ❌ docs/ - Documentation
• ❌ docker-compose.yml - Local development
• ❌ .pre-commit-config.yaml - Dev tools
• ❌ pytest.ini - Test config

---

🎯 Post-Deployment Tasks

1. Run Database Migrations

Migrations run automatically, but you can verify:

# Check Space logs to confirm migrations ran
# Look for: "Running upgrade ... -> ..."

2. Create Admin User

Use the Space's terminal or API to create first admin user:

# Via API (once deployed)
curl -X POST https://[YOUR_SPACE].hf.space/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@swiftops.com",
    "password": "secure_password",
    "name": "Admin User",
    "role": "platform_admin"
  }'

3. Test API Endpoints

# Health check
curl https://[YOUR_SPACE].hf.space/health

# API documentation
open https://[YOUR_SPACE].hf.space/api/docs

---

🔍 Troubleshooting

Build Fails

Check Dockerfile:

• Ensure all paths are correct
• Verify requirements.txt has all dependencies
• Check for syntax errors

Check Logs:

• Go to Space settings → Logs
• Look for error messages during build

Database Connection Issues

Verify Environment Variables:

• Check DATABASE_URL format
• Ensure Supabase allows connections from Hugging Face IPs
• Test connection string locally first

Supabase Configuration:

• Go to Supabase → Settings → Database
• Enable "Allow connections from anywhere" (or add HF IPs)
• Check connection pooling settings

Redis Connection Issues

Verify Redis URL:

• Check REDIS_URL format
• Ensure Redis instance is accessible
• Test connection with redis-cli

Application Errors

Check Logs:

# View Space logs in real-time
# Go to Space → Settings → Logs

Common Issues:

• Missing environment variables
• Database migration failures
• Redis connection timeout
• Port conflicts (should be 7860)

---

📊 Monitoring & Maintenance

View Logs

• Go to Space settings → Logs
• Monitor for errors and warnings

Update Application

# Make changes locally
git add .
git commit -m "Update feature"
git push hf main

# Space will automatically rebuild

Scale Resources

• Go to Space settings → Hardware
• Upgrade to CPU/GPU as needed
• Consider persistent storage for uploads

---

🔒 Security Checklist

• All secrets stored as Space secrets (not in code)
• DEBUG=False in production
• CORS configured properly
• Rate limiting enabled
• Database backups configured (Supabase)
• Redis password protected
• API authentication working
• HTTPS enabled (automatic on HF Spaces)

---

📚 Additional Resources

• Hugging Face Spaces Documentation
• Docker Spaces Guide
• Supabase Documentation
• Upstash Redis Documentation

---

🎉 Success!

Your SwiftOps backend is now deployed on Hugging Face Spaces!

API URL: https://[YOUR_USERNAME]-swiftops-backend.hf.space
API Docs: https://[YOUR_USERNAME]-swiftops-backend.hf.space/api/docs

---

Need help? Check the troubleshooting section or open an issue on GitHub.