docs/hf.md

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:

./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:

HOST_PORT=7861 ./run_docker_local.sh

Deploy (push to Space repo)

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

git push hf main

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

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.