SUPABASE_DEPLOYMENT_GUIDE.md

🚀 Complete Supabase Deployment Guide

Overview

This guide will help you set up your Unified Assistant application with Supabase for both local development and Hugging Face deployment.

🎯 What You'll Learn

1. Local Development Setup - Test with SQLite and Supabase
2. Hugging Face Deployment - Production-ready setup
3. Database Migration - From SQLite to Supabase
4. Testing & Validation - Comprehensive testing scripts

📋 Prerequisites

• Python 3.11+
• Supabase account (free at https://supabase.com)
• OpenAI API key
• Hugging Face account (for deployment)

🛠️ Quick Setup (Recommended)

Step 1: Run the Complete Setup Script

python setup_supabase_complete.py

This interactive script will:

• ✅ Guide you through Supabase setup
• ✅ Configure environment variables
• ✅ Test database connection
• ✅ Create configuration files
• ✅ Generate Hugging Face secrets template

Step 2: Test Your Setup

python test_supabase_complete.py

This comprehensive test will verify:

• ✅ Environment variables
• ✅ Database connection
• ✅ AI services
• ✅ API endpoints
• ✅ Configuration validation

🔧 Manual Setup (Alternative)

1. Create Supabase Project

1. Go to https://supabase.com
2. Sign up/Login with GitHub
3. Click "New Project"
4. Choose organization and project name
5. Set a strong database password
6. Choose a region close to your users
7. Wait for setup to complete (2-3 minutes)

2. Get Database Connection String

1. In your Supabase dashboard, go to Settings → Database
2. Find the Connection string section
3. Copy the URI and modify it:
   • Original: postgresql://postgres:[password]@[host]:5432/postgres
   • Modified: postgresql+asyncpg://postgres:[password]@[host]:5432/postgres

3. Create Environment Files

For Local Development (.env)

# Database Configuration
SUPABASE_DB_URL=postgresql+asyncpg://postgres:[password]@[host]:5432/postgres
DATABASE_URL=sqlite:///./unified_assistant.db
ENVIRONMENT=development
DEBUG=true

# Security
SECRET_KEY=your-secret-key-here

# AI Services
OPENAI_API_KEY=sk-your-openai-key-here

# Application
HOST=0.0.0.0
PORT=7860

For Hugging Face Deployment (secrets)

SUPABASE_DB_URL=postgresql+asyncpg://postgres:[password]@[host]:5432/postgres
ENVIRONMENT=production
SECRET_KEY=your-secret-key-here
OPENAI_API_KEY=sk-your-openai-key-here

🧪 Testing Your Setup

Local Testing

# Test database configuration
python test_database_config.py

# Test complete setup
python test_supabase_complete.py

# Test database connection
python setup_database.py

# Start local server
python main.py

Production Testing

# Test with production environment
ENVIRONMENT=production python test_supabase_complete.py

# Test Hugging Face deployment
python test_supabase.py

🚀 Hugging Face Deployment

1. Prepare Your Repository

Ensure your repository has:

• ✅ main.py (FastAPI application)
• ✅ requirements.txt (dependencies)
• ✅ Dockerfile (container configuration)
• ✅ .dockerignore (exclude unnecessary files)

2. Configure Hugging Face Spaces

1. Go to your Hugging Face Space
2. Navigate to Settings → Repository secrets
3. Add the secrets from huggingface_secrets_template.txt:

SUPABASE_DB_URL=postgresql+asyncpg://postgres:[password]@[host]:5432/postgres
ENVIRONMENT=production
SECRET_KEY=your-secret-key-here
OPENAI_API_KEY=sk-your-openai-key-here

3. Deploy

1. Push your code to the repository
2. Hugging Face will automatically build and deploy
3. Monitor the build logs for any issues
4. Test the deployed application

🔍 Troubleshooting

Common Issues

1. Database Connection Errors

Error: sqlite3.OperationalError: unable to open database file

Solution:

• Set SUPABASE_DB_URL environment variable
• Ensure ENVIRONMENT=production for Hugging Face deployment

2. Missing Environment Variables

Error: SUPABASE_DB_URL environment variable is required

Solution:

• Add SUPABASE_DB_URL to your environment
• Use the setup script: python setup_supabase_complete.py

3. Authentication Errors

Error: authentication failed

Solution:

• Verify your Supabase password
• Check the connection string format
• Ensure you're using postgresql+asyncpg:// not postgresql://

4. Network Connectivity

Error: connection refused

Solution:

• Check if Supabase project is active
• Verify the host and port in connection string
• Test connection locally first

Debug Commands

# Check environment variables
python debug_env.py

# Test database configuration
python test_database_config.py

# Test complete setup
python test_supabase_complete.py

# Check application logs
python main.py

📊 Monitoring & Maintenance

Health Checks

Your application includes health check endpoints:

• /health - Basic health status
• /docs - API documentation
• / - Application information

Database Monitoring

• Supabase provides built-in monitoring
• Check connection pool usage
• Monitor query performance
• Review error logs

Application Logs

The application logs important events:

• Database connection status
• Environment detection
• Error messages
• Startup sequence

🔒 Security Best Practices

Environment Variables

• ✅ Never commit .env files to version control
• ✅ Use Hugging Face secrets for production
• ✅ Rotate secrets regularly
• ✅ Use strong, unique passwords

Database Security

• ✅ Supabase handles SSL automatically
• ✅ Database credentials are encrypted in transit
• ✅ Regular backups are automatic
• ✅ Access is restricted by IP (if configured)

API Security

• ✅ JWT tokens for authentication
• ✅ Secure password hashing
• ✅ Input validation and sanitization
• ✅ Rate limiting (if implemented)

📈 Performance Optimization

Database Optimization

• Connection pooling is configured for Hugging Face Spaces
• Pool size reduced to 5 connections to avoid limits
• Automatic connection recycling every 5 minutes
• Pre-ping enabled for connection health

Application Optimization

• Async database operations
• Efficient query patterns
• Proper indexing (automatic with Supabase)
• Caching where appropriate

🔄 Migration from SQLite

Automatic Migration

The application automatically detects the environment and switches databases:

• Development: Uses SQLite for local testing
• Production: Uses Supabase for deployment
• Hugging Face: Always uses Supabase

Data Migration

If you have existing SQLite data:

1. Export data from SQLite
2. Import to Supabase using their tools
3. Update environment variables
4. Test thoroughly

📞 Support

Getting Help

1. Check the logs - Application provides detailed logging
2. Run tests - Use the provided test scripts
3. Review configuration - Verify environment variables
4. Check Supabase status - Visit Supabase status page

Useful Resources

• Supabase Documentation
• Hugging Face Spaces Guide
• FastAPI Documentation
• SQLAlchemy Documentation

🎉 Success Checklist

Before deploying to production, ensure:

• ✅ Supabase project is created and active
• ✅ Database connection string is correct
• ✅ Environment variables are set
• ✅ All tests pass locally
• ✅ Application starts successfully
• ✅ API endpoints respond correctly
• ✅ Hugging Face secrets are configured
• ✅ Deployment logs show no errors

🚀 Next Steps

After successful setup:

1. Test thoroughly - Use all provided test scripts
2. Deploy to Hugging Face - Follow the deployment guide
3. Monitor performance - Check logs and metrics
4. Scale as needed - Supabase scales automatically
5. Add features - Extend your application

---

Need help? Run python setup_supabase_complete.py for interactive setup assistance!