# Hugging Face Spaces (Docker) — Deploy + Debug

This project is deployed as a Hugging Face Space using the Docker SDK.

## One-time setup (Space UI)

Space: `https://huggingface.co/spaces/MikelWL/ConverTA`

In Space → Settings → Variables and secrets:

**Secrets**
- `LLM_API_KEY`: OpenRouter API key
- `APP_PASSWORD`: shared password to unlock the Space UI (optional but recommended for public Spaces)

**Variables**
- `LLM_BACKEND`: `openrouter`
- `LLM_HOST`: `https://openrouter.ai/api/v1`
- `LLM_MODEL`: e.g. `google/gemini-3-flash-preview`
- `LLM_SITE_URL`: `https://huggingface.co/spaces/MikelWL/ConverTA` (optional)
- `LLM_APP_NAME`: `ConverTA` (optional)
- `FRONTEND_WEBSOCKET_URL`: `ws://127.0.0.1:7860/api/ws/conversation`
- `FRONTEND_BACKEND_BASE_URL`: `http://127.0.0.1:7860/api` (optional)

Restart the Space after changing secrets/variables.

## Local smoke test (HF-like)

Run the Docker image locally before pushing to HF:

```bash
./run_docker_local.sh
```

Then open `http://localhost:7860` and click **Start Conversation**.

If `APP_PASSWORD` is set, you will first see a login page; enter the password to unlock the app.

Note: the local Docker runner forces `FRONTEND_WEBSOCKET_URL` to use the mounted backend (`/api/ws/conversation`) so you don’t accidentally point at `localhost:8000`.

If `7860` is already in use locally, run:

```bash
HOST_PORT=7861 ./run_docker_local.sh
```

## Deploy (push to Space repo)

The Space is also configured as a git remote locally (`hf`).

```bash
git push hf main
```

If the Space repo ever gets reset/recreated and your push is rejected with “fetch first”, use:

```bash
git push --force hf main
```

## Troubleshooting

- **UI loads but analysis never appears / shows backend connection errors**
  - Ensure `FRONTEND_WEBSOCKET_URL` is set to `ws://127.0.0.1:7860/api/ws/conversation`.
- **Space is public but you want to prevent casual usage**
  - Set the `APP_PASSWORD` secret to enable the shared-password login gate.
- **Space crashes on startup**
  - Check Space → Logs for the Python traceback.
  - Confirm `PORT` is being respected (HF sets it automatically; we bind to `0.0.0.0:$PORT`).
- **OpenRouter errors**
  - Confirm `LLM_API_KEY` secret is set and `LLM_MODEL` is valid on OpenRouter.