DEPLOY_HF.md

Deploying to Hugging Face Spaces (Docker)

You can easily deploy this backend to Hugging Face 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.
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!