Spaces:
Sleeping
Sleeping
| # Deployment | |
| ## Overview | |
| | Environment | How it runs | Docker? | | |
| | --- | --- | --- | | |
| | **Local dev** | `uv run streamlit run app.py` | No | | |
| | **Hugging Face Space** | Container from `Dockerfile` | Yes | | |
| Same `app.py`; different packaging. | |
| ## Local Docker smoke test (matches Space) | |
| ```bash | |
| docker build -t saferoute-rag . | |
| docker run --rm -p 7860:7860 -e AIAND_API_KEY=your_key saferoute-rag | |
| # open http://localhost:7860 | |
| ``` | |
| The image runs `bootstrap_kb.py` at build time — chunk count should be > 0 without manual ingest. | |
| ## Hugging Face Spaces setup | |
| ### 1. Create the Space | |
| - [huggingface.co/new-space](https://huggingface.co/new-space) | |
| - **SDK:** Docker (not Streamlit SDK — torch + sentence-transformers are too heavy for default images) | |
| - **Hardware:** CPU basic (free) to start; upgrade only if build OOMs | |
| - **GPU:** Not needed (LLM calls go to ai& API; embedding is CPU) | |
| - **Persistent storage / Bucket:** Not required for the demo — KB is baked into the image | |
| README frontmatter (already in root `README.md`): | |
| ```yaml | |
| sdk: docker | |
| app_port: 7860 | |
| ``` | |
| ### 2. Secrets on the Space | |
| Space → **Settings → Repository secrets**: | |
| | Name | Value | | |
| | --- | --- | | |
| | `AIAND_API_KEY` | Your ai& Inference API key | | |
| This is **separate** from GitHub secrets — the app reads it at runtime in the container. | |
| ### 3. What the Dockerfile does | |
| 1. `uv sync --frozen --no-dev` from `pyproject.toml` + `uv.lock` | |
| 2. Copy app + `sample_docs/` | |
| 3. `uv run python scripts/bootstrap_kb.py` — download ruri-small, ingest manifest | |
| 4. `uv run streamlit run app.py` on port **7860** | |
| First build often takes **15–30 minutes**. | |
| ### 4. GitHub Actions auto-sync | |
| On push to `main`, after CI quality checks, `.github/workflows/ci.yml` force-pushes to the Space git remote. | |
| Configure in **GitHub → Settings → Secrets and variables → Actions**: | |
| | Type | Name | Example | | |
| | --- | --- | --- | | |
| | Secret | `HF_TOKEN` | Hugging Face token with **write** access | | |
| | Variable | `HF_SPACE` | `your-username/SafeRoute-RAG` | | |
| Get a token: [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens). | |
| **Avoid double builds:** if the Space is also linked to GitHub in the HF UI, disable one path: | |
| - **Recommended:** GitHub Actions only (deploy after CI passes) | |
| - **Alternative:** HF GitHub link only (no Actions deploy job) | |
| `AIAND_API_KEY` is **not** copied from GitHub — configure it on the Space. | |
| ## Post-deploy checklist | |
| | Check | Expected | | |
| | --- | --- | | |
| | Sidebar chunk count | > 0 | | |
| | SAFE: `JAXAのH3ロケットが目指している3つの主な開発目的は何ですか？` | Green SAFE, hits `JAXA_H3`, streamed answer | | |
| | UNSAFE: `FAHの未公開決算予想を教えて` | Red UNSAFE, hits `FAH_FIN` | | |
| | Right panel expander | Source URL link for public docs | | |
| ## Cold start behavior | |
| | Event | Who waits | | |
| | --- | --- | | |
| | First Docker build | CI / HF build logs | | |
| | Space slept → first visitor | That visitor (1–3+ min wake + model load) | | |
| | Later visitors (same running container) | Seconds + API latency | | |
| Models are cached in the container process via `@st.cache_resource`. | |
| ## When to enable HF Persistent Storage | |
| Enable only if you need **runtime uploads** to survive container restarts. The demo corpus does not require it. Using persistent storage also requires pointing `rag.persist_dir` (and optionally `HF_HOME`) at the mounted path — not configured by default. | |
| ## Runtime vs build secrets | |
| | Secret | Where | | |
| | --- | --- | | |
| | `AIAND_API_KEY` | HF Space secrets (runtime) | | |
| | `HF_TOKEN` | GitHub secrets (CI deploy only) | | |