chatkit/DEPLOY.md

# 🚀 Deploy ClassLens to Hugging Face Spaces

## Prerequisites

1. Hugging Face account with access to [taboola-cz](https://huggingface.co/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

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

## Step 2: Push the Code

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

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

```bash
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](https://console.cloud.google.com/apis/credentials)
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

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

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