HUGGINGFACE_DEPLOYMENT.md

Hugging Face Spaces Deployment Guide

This guide explains how to deploy Open Notebook to Hugging Face Spaces using the Docker SDK.

Files Created

1. Dockerfile.huggingface - Docker configuration for single-container deployment
2. start.sh - Startup script that launches SurrealDB and FastAPI
3. open_notebook/database/connection.py - SurrealDB connection with retry logic
4. requirements.txt - Python dependencies extracted from pyproject.toml
5. README_HUGGINGFACE.md - Hugging Face Spaces README

Deployment Steps

1. Rename Dockerfile

# Rename the Hugging Face Dockerfile to the standard name
mv Dockerfile.huggingface Dockerfile

2. Create Hugging Face Space

1. Go to huggingface.co/new-space
2. Choose:
   • Space name: open-notebook (or your preferred name)
   • License: MIT
   • SDK: Docker
   • Visibility: Public or Private

3. Push Code to Hugging Face

# Add Hugging Face remote
git remote add hf https://huggingface.co/spaces/YOUR_USERNAME/open-notebook

# Push to Hugging Face
git push hf main

4. Configure Secrets

In your Hugging Face Space settings, add these secrets:

Required (add at least one):

• OPENAI_API_KEY - Your OpenAI API key
• ANTHROPIC_API_KEY - Your Anthropic (Claude) API key
• GOOGLE_API_KEY - Your Google (Gemini) API key

Optional:

• GROQ_API_KEY - Groq API key
• MISTRAL_API_KEY - Mistral API key

5. Wait for Build

Hugging Face will automatically build your Docker container. This takes about 10-15 minutes.

Important Notes

Port Configuration

Hugging Face Spaces requires port 7860. The Dockerfile is configured to use this port.

In-Memory Storage

This deployment uses SurrealDB in memory mode (memory). This means:

• ✅ Fast performance
• ✅ No disk space issues
• ❌ Data is lost when container restarts
• ❌ Not suitable for production

For persistent storage, modify start.sh:

# Change from:
surreal start --log debug --user root --pass root memory &

# To:
surreal start --log debug --user root --pass root file://data/database.db &

Retry Logic

The connection module (open_notebook/database/connection.py) includes:

• 5 retry attempts with exponential backoff
• 2-second initial delay, increasing with each retry
• Ensures SurrealDB is ready before FastAPI starts accepting requests

Resource Limits

Hugging Face Spaces free tier:

• 2 CPU cores
• 16GB RAM
• 50GB disk (ephemeral)

The sentence-transformer model (all-MiniLM-L6-v2) is pre-downloaded during build to avoid startup delays.

Testing Your Deployment

Once deployed, test these endpoints:

# Health check
curl https://YOUR_USERNAME-open-notebook.hf.space/health

# API documentation
https://YOUR_USERNAME-open-notebook.hf.space/docs

# Create a notebook
curl -X POST https://YOUR_USERNAME-open-notebook.hf.space/api/notebooks \
  -H "Content-Type: application/json" \
  -d '{"name": "Test Notebook", "description": "My first notebook"}'

Troubleshooting

Build Fails

Check the build logs in Hugging Face. Common issues:

• Missing dependencies: Verify all packages in requirements.txt
• SurrealDB install fails: Check internet connectivity during build
• Out of memory: Reduce the size of pre-downloaded models

Runtime Errors

Check the runtime logs:

• "Connection refused": SurrealDB didn't start - increase wait time in start.sh
• "Database migration failed": Check SURREAL_* environment variables
• "Model not found": Ensure sentence-transformers model downloaded during build

Performance Issues

On free tier:

• Limit concurrent requests
• Use lighter LLM models (Gemini, GPT-3.5-turbo)
• Reduce chunk size for embeddings
• Enable caching for repeated queries

Upgrading to Persistent Storage

To use external SurrealDB with persistent storage:

1. Deploy SurrealDB separately (Railway, Fly.io, etc.)
2. Update environment variables in Hugging Face settings:

   SURREAL_URL=wss://your-surrealdb-instance.com/rpc
   SURREAL_USER=your_username
   SURREAL_PASS=your_password
   

3. Remove SurrealDB startup from start.sh:

   #!/bin/bash
   set -e
   echo "Starting FastAPI application on port 7860..."
   exec uvicorn api.main:app --host 0.0.0.0 --port 7860
   

Alternative Deployment: Split Services

For better performance, consider splitting frontend and backend:

Backend Space (this configuration):

• Python Docker SDK
• FastAPI + SurrealDB
• Port 7860

Frontend Space (separate):

• Node.js SDK or Static
• Next.js frontend
• Points to backend API

Cost Optimization

Free Tier Recommendations:

• Use Google Gemini (free tier: 60 requests/min)
• Pre-generate embeddings during low traffic
• Implement request queuing
• Cache LLM responses

Paid Tier Benefits ($9/month):

• No cold starts
• More CPU/RAM
• Persistent storage
• Custom domains

Security Considerations

1. Never commit API keys - Use Hugging Face Secrets
2. Enable authentication - Modify api/auth.py to add user login
3. Rate limiting - Add rate limits to prevent abuse
4. CORS configuration - Restrict allowed origins in production
5. Input validation - All file uploads should be validated

Support

• Discord: https://discord.gg/37XJPXfz2w
• GitHub Issues: https://github.com/baveshraam/software-eng-proj/issues
• Documentation: https://www.open-notebook.ai