Spaces:
Running
Running
| title: HF Backend | |
| emoji: ⚡ | |
| colorFrom: purple | |
| colorTo: indigo | |
| sdk: docker | |
| app_port: 7860 | |
| # HF Backend | |
| FastAPI host running on a Hugging Face Docker Space. It mounts backend routers from separate project repositories under specific URL prefixes. | |
| ## How it works | |
| The host application does not define business logic. Each subproject lives in its own repository, exposes a router in `<package>/router.py`, and is installed as a Python package. | |
| The host imports each router dynamically from `registry.py` and mounts it under a prefix. If an individual router fails to import, the host logs the error, records the failure, and keeps running for the other services. | |
| ``` | |
| /project-1/* -> HEARTFLOW_OS backend router | |
| /project-2/* -> Semantic Comment Analyzer backend router | |
| /health -> Host health status | |
| ``` | |
| ## Adding a project | |
| Adding a new service takes two steps: | |
| 1. Add the prefix and router path to `registry.py`: | |
| ```python | |
| PROJECT_REGISTRY = { | |
| "/project-1": "heartflow_backend.router:router", | |
| "/project-2": "semantic_backend.router:router", | |
| "/project-3": "new_project.router:router", | |
| } | |
| ``` | |
| 2. Add the pinned Git tag to `requirements.txt`: | |
| ```text | |
| git+https://github.com/<user>/<repo>.git@v1.0#subdirectory=backend | |
| ``` | |
| Pushing to `main` syncs the change to Hugging Face and rebuilds the Space container. | |
| ## Configuration | |
| Set these in the Space settings under **Variables and secrets**: | |
| | Variable | Required | Default | Notes | | |
| | :--- | :--- | :--- | :--- | | |
| | `CORS_ALLOWED_ORIGINS` | No | None | Comma-separated allowed origins. Wildcards (`*`) are ignored. | | |
| | `DISABLE_PROJECTS` | No | None | Comma-separated prefixes to skip loading (e.g. `project-2`). | | |
| | `MAX_BODY_SIZE_BYTES` | No | 10485760 (10 MB) | Max request body size before returning 413. | | |
| | `REQUEST_TIMEOUT_SECONDS` | No | 60.0 | Request timeout before returning 504. | | |
| | `GITHUB_TOKEN` | Only for private repos | None | GitHub token passed as a build secret to clone private dependencies. | | |
| GitHub repository secrets (used by GitHub Actions): | |
| | Secret | Notes | | |
| | :--- | :--- | | |
| | `HF_BACKEND_SPACE` | Hugging Face write token used to push code and trigger Space restart. | | |
| | `HF_SPACE_URL` | Optional. Health URL for the keep-alive workflow. | | |
| ## Endpoints | |
| ### `GET /health` | |
| Returns the status of the host and each registered project. | |
| ```json | |
| { | |
| "status": "healthy", | |
| "loaded": { | |
| "/project-1": "heartflow_backend.router:router", | |
| "/project-2": "semantic_backend.router:router" | |
| }, | |
| "failed": {} | |
| } | |
| ``` | |
| If any service fails to load, `status` changes to `"degraded"` or `"unhealthy"` and the error is listed under `"failed"`. | |
| Interactive documentation (`/docs`, `/redoc`, `/openapi.json`) is disabled. | |
| ## Release workflow | |
| 1. Test changes in the project repository using its `dev.py`. | |
| 2. Tag the release (`git tag v1.0`, `git push origin v1.0`). | |
| 3. Update the tag in this repo's `requirements.txt`. | |
| 4. Push to `main`. The GitHub Actions workflow pushes to Hugging Face and restarts the Space. | |