| # 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. | |