DEPLOY_HF.md

# Deploying to Hugging Face Spaces (Docker)

You can easily deploy this backend to [Hugging Face Spaces](https://huggingface.co/spaces) using their Docker SDK.

## Prerequisites

1. A Hugging Face account.
2. `pyproject.toml` and `uv.lock` must be in the backend directory.

## Deployment Steps

### 1. Create a New Space

1. Go to [Creates a new Space](https://huggingface.co/new-space).
2. **Space Name**: e.g., `chatkit-backend`.
3. **License**: Apache 2.0 or MIT.
4. **SDK**: Select **Docker**.
5. **Template**: Choose "Blank".
6. **Space Hardware**: CPU Basic (Free) is usually enough for this middleware (since generic LLM inference happens externally).

### 2. Configure the Space

Hugging Face Spaces expects the application to listen on port **7860**.

**Option A: Push via Git (Recommended)**

You can simply push your `backend` folder contents to the Space's repository. Note that the Space root must be the directory containing the `Dockerfile`.

If your repo has `backend/Dockerfile`, you might need to adjust the structure or use the "Docker options" in `README.md` (of the space) to point to the correct folder, OR simply copy the backend contents to the root of the Space repo.

**Option B: Adjust Dockerfile for Port 7860**

Your `Dockerfile` currently defaults to port 8000. Hugging Face sets the `PORT` environment variable to `7860` automatically in most cases, but to be safe, you can update your Dockerfile or just rely on the env var override.

**Env Var Override:**  
The existing Dockerfile uses:  
`CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]`

To make it compatible with HF's dynamic port, update the `CMD` in `Dockerfile` to use the shell form or rely on the host variable if we use a starter script. Or simpler, just change the default to 7860.

### 3. Persisting Data (SQLite)

On Hugging Face Spaces (Free Tier), the filesystem is **ephemeral**. This means **your database (`chatkit_threads.db`) will be deleted** every time the Space restarts (which happens frequently).

**To keep your chat history:**
1. Go to your Space **Settings**.
2. Scroll to "Persistent Storage".
3. You can upgrade to a paid tier to get a persistent volume mounted at `/data`.

If you enable persistent storage:
1. Update your Environment Variables (see step 4) to save DBs in `/data`.
   - `CHATKIT_DB_PATH` = `/data/chatkit_threads.db`
   - `USER_STATE_DB_PATH` = `/data/user_state.db`

### 4. Set Secrets (Environment Variables)

Go to your Space -> **Settings** -> **Variables and secrets**.

Add the following **Secrets** (Copy from your `.env.local`):

- `GROQ_API_KEY`
- `OPENAI_API_KEY`
- `OPENROUTER_API_KEY`
- `DEEPSEEK_API_KEY`
- `GOOGLE_API_KEY`
- `CARTESIA_API`

And add the following **Variables** (if using persistent storage):
- `CHATKIT_DB_PATH` = `chatkit_threads.db` (or `/data/...`)
- `USER_STATE_DB_PATH` = `user_state.db` (or `/data/...`)

### 5. Finalize

Once the files are pushed and secrets set, the Space will build locally. Open the **App** tab to see your running backend. The URL will be something like `https://huggingface.co/spaces/<username>/<space-name>`.

You can now point your frontend to this URL!