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](https://huggingface.co)
2. **Hugging Face Token**: Get your token from [Settings → Access Tokens](https://huggingface.co/settings/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](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)

```bash
# 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

```env
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):

```env
GROQ_API_KEY=your_groq_api_key
LLM_BACKEND=groq
```

#### Optional Variables

```env
# 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](https://huggingface.co/docs/hub/spaces)
- [Docker on Hugging Face Spaces](https://huggingface.co/docs/hub/spaces-sdks-docker)
- [Environment Variables Guide](https://huggingface.co/docs/hub/spaces-config#environment-variables)

## ✅ 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](#-troubleshooting) section or open an issue in the repository.