Spaces:
Running
Running
File size: 3,011 Bytes
2322c22 104d5d9 2322c22 104d5d9 2322c22 104d5d9 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 | ---
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.
|