DEPLOY_HF_SPACES.md

Deploying IntegraChat to Hugging Face Spaces

This guide walks you through deploying IntegraChat as a Hugging Face Space.

📋 Prerequisites

1. Hugging Face Account: Sign up at huggingface.co
2. Hugging Face Token: Get your token from Settings → Access Tokens
3. Required Services (configure via environment variables):
   • PostgreSQL with pgvector (for RAG storage)
   • Ollama (local LLM) or Groq API (cloud LLM)
   • Optional: Supabase (for production storage)
   • Optional: Google Custom Search API (for web search)

🚀 Step-by-Step Deployment

Step 1: Create a New Space

1. Go to https://huggingface.co/new-space
2. Fill in the form:
   • Space name: integrachat (or your preferred name)
   • SDK: Select Docker
   • Hardware: Choose based on your needs:
     • CPU basic - For testing (free tier)
     • CPU upgrade - Better performance (paid)
     • GPU - If you need GPU acceleration (paid)
   • Visibility: Public or Private
3. Click Create Space

Step 2: Prepare Your Repository

Your project structure should look like this:

IntegraChat/
├── Dockerfile              ✅ (created)
├── .dockerignore           ✅ (created)
├── README_HF_SPACES.md     ✅ (created)
├── requirements.txt        ✅ (already exists)
├── app.py                  ✅ (already exists)
├── env.example             ✅ (already exists)
├── LICENSE                  ✅ (already exists)
├── README.md               ✅ (already exists)
├── assets/
│   └── banner.png          ✅ (already exists)
├── backend/                ✅ (entire directory)
└── scripts/                ✅ (if you have any)

Step 3: Push to Hugging Face

Option A: Using Git (Recommended)

# Initialize git if not already done
git init

# Add Hugging Face remote
git remote add hf https://huggingface.co/spaces/<your-username>/<space-name>

# Add all files (except venv)
git add Dockerfile .dockerignore README_HF_SPACES.md requirements.txt app.py env.example LICENSE README.md assets/ backend/ scripts/

# Commit
git commit -m "Initial commit for HF Spaces deployment"

# Push to Hugging Face
git push hf main

Option B: Using Hugging Face Web Interface

1. Go to your Space page
2. Click Files and versions tab
3. Click Upload files
4. Upload all necessary files (drag and drop or select files)

Step 4: Configure Environment Variables

1. Go to your Space page
2. Click Settings tab
3. Scroll to Repository secrets section
4. Add the following environment variables:

Required Variables

POSTGRESQL_URL=postgresql://user:password@host:port/database
OLLAMA_URL=http://your-ollama-server:11434
OLLAMA_MODEL=llama3.1:latest

OR (if using Groq instead of Ollama):

GROQ_API_KEY=your_groq_api_key
LLM_BACKEND=groq

Optional Variables

# Supabase (for production storage)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your_service_role_key

# Google Custom Search (for web search)
GOOGLE_SEARCH_API_KEY=your_google_api_key
GOOGLE_SEARCH_CX_ID=your_search_engine_id

# MCP Server Configuration
MCP_PORT=8900
MCP_HOST=0.0.0.0

# API Configuration
API_PORT=8000
BACKEND_BASE_URL=http://localhost:8000

# Memory Configuration
MCP_MEMORY_MAX_ITEMS=10
MCP_MEMORY_TTL_SECONDS=900

# Logging
LOG_LEVEL=info
APP_ENV=production

Step 5: Wait for Build

1. After pushing, Hugging Face will automatically start building your Docker image
2. You can monitor the build progress in the Logs tab
3. Build typically takes 5-10 minutes for the first time
4. Once built, your Space will be available at: https://huggingface.co/spaces/<your-username>/<space-name>

Step 6: Verify Deployment

1. Check Logs: Go to the Logs tab to see if all services started correctly
2. Test UI: Open your Space URL and verify the Gradio UI loads
3. Test API: Try accessing https://<your-space-url>/api/docs for FastAPI docs
4. Test Health: Check https://<your-space-url>/api/health for backend health

🔧 Troubleshooting

Build Fails

• Check Dockerfile syntax: Ensure all commands are valid
• Check requirements.txt: Verify all packages are available on PyPI
• Check logs: Review build logs for specific errors
• Common issues:
  • Missing system dependencies → Add to apt-get install in Dockerfile
  • Python version mismatch → Update FROM python:3.10-slim if needed
  • Port conflicts → Ensure ports 7860, 8000, 8900 are exposed

Services Not Starting

• Check environment variables: Ensure all required vars are set
• Check service logs: Review logs for MCP server and FastAPI errors
• Database connection: Verify PostgreSQL URL is correct and accessible
• LLM connection: Verify Ollama URL or Groq API key is valid

UI Not Loading

• Check Gradio logs: Look for errors in the Logs tab
• Check port binding: Ensure Gradio binds to 0.0.0.0:7860
• Check backend connection: Verify BACKEND_BASE_URL is correct

API Endpoints Not Working

• Check FastAPI logs: Review backend startup logs
• Check MCP server: Ensure MCP server is running on port 8900
• Check CORS: Verify CORS middleware is configured correctly
• Check headers: Ensure x-tenant-id and x-user-role headers are sent

📝 Important Notes

1. Port Configuration:

   • Hugging Face Spaces automatically maps port 7860 to the public URL
   • Internal services (FastAPI on 8000, MCP on 8900) are accessible within the container
   • Use localhost for inter-service communication

2. Database Access:

   • Your PostgreSQL database must be accessible from Hugging Face's servers
   • Consider using a cloud database (Supabase, AWS RDS, etc.)
   • Ensure firewall rules allow connections from Hugging Face IPs

3. LLM Access:

   • If using Ollama, it must be accessible from Hugging Face servers
   • Consider using Groq API for cloud-based LLM access
   • Or use Hugging Face's Inference API

4. Resource Limits:

   • Free tier has CPU and memory limits
   • Consider upgrading for production use
   • Monitor resource usage in the Space settings

5. Secrets Management:

   • Never commit .env files with secrets
   • Use Hugging Face Space secrets for sensitive data
   • Use env.example as a template

🎯 Next Steps

1. Customize README: Update README_HF_SPACES.md with your specific details
2. Add Banner: Upload a banner image to assets/banner.png
3. Test Thoroughly: Test all features in the deployed environment
4. Monitor Usage: Check Space analytics for usage patterns
5. Update Documentation: Keep documentation in sync with deployment

📚 Additional Resources

• Hugging Face Spaces Documentation
• Docker on Hugging Face Spaces
• Environment Variables Guide

✅ Checklist

Before deploying, ensure:

• Dockerfile is present and valid
• .dockerignore excludes venv and .env
• requirements.txt includes all dependencies
• Environment variables are documented
• Database is accessible from Hugging Face servers
• LLM service is configured (Ollama or Groq)
• README_HF_SPACES.md is customized
• All code is committed and pushed

---

Need Help? Check the Troubleshooting section or open an issue in the repository.