chatkit/DEPLOY.md

🚀 Deploy ClassLens to Hugging Face Spaces

Prerequisites

1. Hugging Face account with access to taboola-cz organization
2. Git installed
3. OpenAI API key

Step 1: Create the Space

Option A: Via Hugging Face Web UI

1. Go to https://huggingface.co/new-space?owner=taboola-cz
2. Fill in:
   • Space name: examinsight
   • License: MIT
   • SDK: Docker
   • Visibility: Public (or Private)
3. Click "Create Space"

Option B: Via Git

# Clone the empty space
git clone https://huggingface.co/spaces/taboola-cz/examinsight
cd examinsight

Step 2: Push the Code

# From the examinsight-app/chatkit directory
cd /path/to/ClassLens/examinsight-app/chatkit

# Add HF as remote
git remote add hf https://huggingface.co/spaces/taboola-cz/examinsight

# Push to HF Spaces
git push hf main

Or copy files manually:

# Copy necessary files to the HF Space repo
cp -r backend frontend Dockerfile README.md .dockerignore /path/to/examinsight-space/

Step 3: Configure Secrets

Go to your Space settings: https://huggingface.co/spaces/taboola-cz/examinsight/settings

Add these Repository secrets:

Secret Name	Description	Required
OPENAI_API_KEY	Your OpenAI API key	✅ Yes
ENCRYPTION_KEY	Fernet key for token encryption	✅ Yes
GOOGLE_CLIENT_ID	Google OAuth client ID	Optional
GOOGLE_CLIENT_SECRET	Google OAuth secret	Optional
GOOGLE_REDIRECT_URI	https://taboola-cz-examinsight.hf.space/auth/callback	Optional
GMAIL_USER	Gmail address for sending reports	Optional
GMAIL_APP_PASSWORD	Gmail App Password	Optional
VITE_CHATKIT_API_DOMAIN_KEY	ChatKit domain key	✅ Yes

Generate Encryption Key

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

Get ChatKit Domain Key

1. Go to https://platform.openai.com/settings/organization/security/domain-allowlist
2. Add domain: taboola-cz-examinsight.hf.space
3. Copy the generated domain key

Step 4: Update Google OAuth (if using)

1. Go to Google Cloud Console
2. Edit your OAuth 2.0 Client
3. Add to Authorized redirect URIs:

   https://taboola-cz-examinsight.hf.space/auth/callback
   

4. Add to Authorized JavaScript origins:

   https://taboola-cz-examinsight.hf.space
   

Step 5: Deploy

The Space will automatically build when you push. Watch the build logs at: https://huggingface.co/spaces/taboola-cz/examinsight/logs

File Structure for HF Spaces

examinsight/
├── Dockerfile          # Multi-stage build
├── README.md           # Space config (YAML frontmatter)
├── .dockerignore       # Files to exclude from build
├── backend/
│   ├── pyproject.toml
│   └── app/
│       ├── main.py     # FastAPI + static file serving
│       ├── server.py   # ChatKit agent
│       └── ...
└── frontend/
    ├── package.json
    └── src/
        └── ...

Troubleshooting

Build Failed

Check the build logs for errors:

• Missing dependencies → Update pyproject.toml
• Node version issues → Update Dockerfile

ChatKit Not Working

1. Verify OPENAI_API_KEY is set in secrets
2. Verify VITE_CHATKIT_API_DOMAIN_KEY is set and valid
3. Check that domain is allowlisted in OpenAI dashboard

Google OAuth Not Working

1. Verify redirect URI matches exactly
2. Check that test users are added (if app is in testing mode)
3. Verify Google Cloud APIs are enabled

Static Files Not Serving

1. Check that frontend build succeeded (look for /static/index.html in container)
2. Verify STATIC_DIR path in main.py

Local Testing with Docker

# Build the image
docker build -t examinsight .

# Run with env file
docker run -p 7860:7860 --env-file .env examinsight

# Open http://localhost:7860

Updating the Space

# Make changes locally
# Commit and push
git add .
git commit -m "Update feature X"
git push hf main

The Space will automatically rebuild.

---

Quick Reference

URL	Description
https://huggingface.co/spaces/taboola-cz/examinsight	Live Space
https://huggingface.co/spaces/taboola-cz/examinsight/settings	Settings & Secrets
https://huggingface.co/spaces/taboola-cz/examinsight/logs	Build & Runtime Logs
https://platform.openai.com/settings/organization/security/domain-allowlist	ChatKit Domain Keys