Hugging Face Spaces Deployment Guide

🚨 Important: Database Configuration Fix

If you're experiencing sqlite3.OperationalError: unable to open database file errors:

The application has been updated to automatically detect Hugging Face deployment and require Supabase database configuration. SQLite does not work in the containerized Hugging Face environment.

Quick Fix: Set the SUPABASE_DB_URL environment variable in your Hugging Face Space secrets.

Quick Setup for Production

1. Create Supabase Database

Go to https://supabase.com
Create a new project
Get your database connection string from Settings → Database

2. Configure Hugging Face Spaces

Go to your Hugging Face Space
Navigate to Settings → Repository secrets
Add these environment variables:

SUPABASE_DB_URL=postgresql+asyncpg://postgres:[YOUR_PASSWORD]@[YOUR_HOST]:5432/postgres
ENVIRONMENT=production
OPENAI_API_KEY=your_openai_api_key_here
SECRET_KEY=your_secret_key_here

3. Deploy

The application will automatically:

✅ Detect Hugging Face deployment environment
✅ Use Supabase database connection
✅ Create all necessary database tables
✅ Start the FastAPI server

Environment Variables

Variable	Description	Required	Example
`SUPABASE_DB_URL`	PostgreSQL connection string	✅ Yes	`postgresql+asyncpg://postgres:password@host:5432/postgres`
`ENVIRONMENT`	Set to "production"	✅ Yes	`production`
`OPENAI_API_KEY`	Your OpenAI API key	✅ Yes	`sk-...`
`SECRET_KEY`	Secret key for JWT tokens	✅ Yes	`your-secret-key`
`HF_API_TOKEN`	Hugging Face API token	Optional	`hf_...`

What's New in This Update

1. Enhanced Environment Detection

Automatically detects Hugging Face deployment environment
Requires Supabase configuration in production
Provides clear error messages for missing configuration

2. Better Error Handling

Clear error messages guide you to set required environment variables
Automatic fallback detection between SQLite (development) and Supabase (production)
Improved logging for debugging

3. Database Configuration

Automatic database type detection (SQLite vs PostgreSQL)
Optimized connection pooling for Hugging Face Spaces
Better error messages for database connection issues

Testing Your Configuration

Run the test script to verify your database configuration:

python test_database_config.py

This will check:

✅ Environment variable configuration
✅ Database connection settings
✅ Actual database connectivity

Troubleshooting

Database Connection Issues

If you see sqlite3.OperationalError: unable to open database file:

Set SUPABASE_DB_URL: This is now required for Hugging Face deployment
Check Environment Variables: Ensure SUPABASE_DB_URL is set correctly
Verify Supabase: Make sure your Supabase project is active
Check Network: Ensure Hugging Face can reach your Supabase instance

Common Error Messages

❌ SUPABASE_DB_URL environment variable is required for Hugging Face deployment

→ Solution: Set SUPABASE_DB_URL environment variable in your Hugging Face Space secrets

❌ Failed to create database tables: [Errno 2] No such file or directory

→ Solution: Set SUPABASE_DB_URL environment variable

❌ Database connection failed: connection refused

→ Solution: Check your Supabase connection string

❌ Database connection failed: authentication failed

→ Solution: Verify your Supabase password

Testing Your Deployment

Health Check: Visit /health endpoint
API Docs: Visit /docs for interactive API documentation
Database Test: The app will log database connection status on startup
Configuration Test: Run python test_database_config.py locally

Monitoring

Check the Hugging Face Spaces logs for:

✅ Environment detection successful
✅ Supabase database configuration detected
✅ Database connection successful
✅ Database tables created successfully
✅ Application startup complete

Security Notes

✅ Never commit .env files to version control
✅ Use Hugging Face secrets for all sensitive data
✅ Supabase automatically handles SSL connections
✅ Database credentials are encrypted in transit

Support

If you encounter issues:

Check the logs in Hugging Face Spaces
Run python test_database_config.py to verify configuration
Verify your Supabase configuration
Test the database connection locally first
Review the SUPABASE_SETUP.md guide for detailed instructions
Check HUGGINGFACE_DEPLOYMENT_FIX.md for specific deployment fixes