Switch deploy to HF Static Space (frontend) + separate API

Hugging Face only offers free Static Spaces (Docker requires a paid plan),
so the frontend now deploys to a Static Space and the API to any Python
host:

- README front matter -> sdk: static with app_build_command building
frontend/ and serving frontend/dist.
- Frontend resolves the API base at runtime from the HF Space variable
DOCUASK_API_URL (via window.huggingface.variables), then VITE_API_URL,
then /api — so the API URL changes without a rebuild.
- Backend CORS default now includes the Static Space origin; backend
Dockerfile honors and a Procfile is added for native-Python hosts.
- Deploy docs rewritten for the split; the single-image Docker option
(root Dockerfile + app/server.py) is kept as an alternative.

Sync workflow and tests unchanged in behavior; 21 backend tests pass and
the frontend builds.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WN4QRr6dTE2W7hQ2SDnLmY

.github/workflows/sync-to-hf.yml

@@ -1,8 +1,8 @@
 name: Sync to Hugging Face Space
 
-# Mirrors the default branch to a Hugging Face Space on every push, so the live
-# demo tracks main. The Space builds the root Dockerfile (see README front
-# matter).
+# Mirrors the default branch to a Hugging Face Static Space on every push, so
+# the live demo tracks main. The Space builds the frontend (see the
+# app_build_command in the README front matter) and serves frontend/dist.
 #
 # One-time setup (GitHub → Settings → Secrets and variables → Actions):
 #   - Secret   HF_TOKEN     : a Hugging Face access token with write scope

PROJECT_SPEC.md

@@ -119,9 +119,10 @@ Goal: live URL + green CI + a README a recruiter can skim.
 - README: one-paragraph description, screenshot/GIF of the chat + dashboard,
   live demo link, run instructions, tech stack.
 
-> Note: this project deploys as a single-image **Hugging Face Space** (Docker),
-> which serves the frontend and API from one origin — replacing the split
-> Render/Vercel plan above.
+> Note: this project deploys the frontend to a **Hugging Face Static Space**
+> (HF builds `frontend/` and serves it) and the API to any Python host, wired by
+> the `DOCUASK_API_URL` Space variable. A single-image Docker option
+> (`Dockerfile` + `app/server.py`) is also included for one-origin hosting.
 
 **Acceptance criteria**
 

README.md

@@ -3,8 +3,9 @@ title: DocuAsk
 emoji: 📄
 colorFrom: green
 colorTo: gray
-sdk: docker
-app_port: 7860
+sdk: static
+app_build_command: cd frontend && npm ci && npm run build
+app_file: frontend/dist/index.html
 pinned: false
 license: mit
 ---
@@ -94,25 +95,45 @@ every push.
 | POST   | `/feedback`         | Attach 👍/👎 (`up`/`down`) to an interaction.       |
 | GET    | `/stats`            | Totals, median latency, thumbs-up rate, over-time. |
 
-## Deploy (Hugging Face Spaces)
+## Deploy
 
-The root [`Dockerfile`](./Dockerfile) builds a **single image** that serves the
-React frontend and the API from one origin (the API is mounted under `/api`), so
-you get one live URL with no CORS to configure.
+The frontend deploys to a **Hugging Face Static Space** and the API to any host
+that runs a Python web process. They're wired together with one Space variable —
+no rebuild needed to change the API URL.
 
-1. Create a new **Space** → **Docker** SDK (blank template).
-2. Push this repository to the Space (or connect the GitHub repo). The Space
-   reads the YAML front matter at the top of this README (`sdk: docker`,
-   `app_port: 7860`) and builds the root `Dockerfile`.
-3. Wait for the build; the app comes up at your Space URL. Paste that URL into
-   the **Live demo** link above.
+### 1. Frontend → Hugging Face Static Space
 
-Telemetry uses `/tmp/docuask.db` by default (resets on restart). To persist it,
-add HF **persistent storage** and set `DOCUASK_DB=/data/docuask.db` in the
-Space's variables.
+The README front matter (`sdk: static`) tells HF to run the
+`app_build_command` (`cd frontend && npm ci && npm run build`) and serve
+`frontend/dist`.
 
-**Keep the demo in sync automatically.** The
-[`sync-to-hf`](./.github/workflows/sync-to-hf.yml) workflow mirrors `main` to
+1. Create a new **Space** → **Static** SDK, owner `Sri-28`, name `docuask`.
+2. Push this repo to the Space (the [`sync-to-hf`](./.github/workflows/sync-to-hf.yml)
+   workflow does this automatically — see below).
+3. In the Space's **Settings → Variables**, add `DOCUASK_API_URL` set to your
+   deployed API's URL. The frontend reads it at runtime via
+   `window.huggingface.variables`, so you can change it without rebuilding.
+
+The Space serves at **https://sri-28-docuask.static.hf.space**.
+
+### 2. Backend → your host
+
+The API is a standard uvicorn app; deploy it however you like:
+
+- **Docker host** (Fly.io, Railway, …): build [`backend/Dockerfile`](./backend/Dockerfile)
+  — it honors `$PORT`.
+- **Native Python host** (Render web service, Railway, …): use
+  [`backend/Procfile`](./backend/Procfile) —
+  `uvicorn app.main:app --host 0.0.0.0 --port $PORT`.
+
+The Static Space origin (`https://sri-28-docuask.static.hf.space`) is already in
+the backend's default CORS allow-list; add more origins via the `CORS_ORIGINS`
+env var. Set `DOCUASK_DB` to a path on persistent storage to keep telemetry
+across restarts. See [`backend/.env.example`](./backend/.env.example).
+
+### Keep the demo in sync automatically
+
+The [`sync-to-hf`](./.github/workflows/sync-to-hf.yml) workflow mirrors `main` to
 your Space on every push. Configure it once under **Settings → Secrets and
 variables → Actions**:
 
@@ -122,9 +143,10 @@ variables → Actions**:
 
 Until `HF_TOKEN` is set the workflow no-ops, so it never fails the branch.
 
-> Prefer split hosting (e.g. static frontend + separate API)? Set
-> `VITE_API_URL` at frontend build time to the API origin and add that origin to
-> the backend's `CORS_ORIGINS`. See the `.env.example` files.
+> **One-origin alternative:** the root [`Dockerfile`](./Dockerfile) +
+> [`app/server.py`](./backend/app/server.py) build a single image that serves the
+> frontend and API together under one origin (API mounted at `/api`, no CORS).
+> Use this on any Docker host if you'd rather run one service than two.
 
 ## Project structure
 
@@ -156,7 +178,7 @@ docuask/
 - **Persistence:** SQLite (interaction telemetry)
 - **Tests:** pytest
 - **CI:** GitHub Actions (pytest + build on every push)
-- **Deploy:** Docker (single-image Hugging Face Space); Docker Compose locally
+- **Deploy:** Hugging Face Static Space (frontend) + any Python host (API); Docker Compose locally
 
 ## Roadmap
 

backend/Dockerfile

@@ -16,4 +16,6 @@ RUN apt-get update \
     && apt-get install -y --no-install-recommends curl libgomp1 \
     && rm -rf /var/lib/apt/lists/*
 
-CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
+# Honor $PORT when the host injects one (Railway, Fly, Render, …); default 8000
+# for docker-compose, which maps and health-checks 8000.
+CMD ["sh", "-c", "uvicorn app.main:app --host 0.0.0.0 --port ${PORT:-8000}"]

backend/Procfile

@@ -0,0 +1 @@
+web: uvicorn app.main:app --host 0.0.0.0 --port $PORT

backend/app/main.py

@@ -26,9 +26,13 @@ logger = logging.getLogger("docuask")
 # exhaust memory. 10 MB comfortably covers real documents.
 MAX_UPLOAD_BYTES = 10 * 1024 * 1024
 
-# Comma-separated list of allowed origins. Defaults cover the Vite dev server
-# and a locally served production build. Override in deployment via env var.
-_DEFAULT_ORIGINS = "http://localhost:5173,http://127.0.0.1:5173,http://localhost:4173"
+# Comma-separated list of allowed origins. Defaults cover the Vite dev server,
+# a locally served production build, and the DocuAsk Hugging Face Static Space
+# (the deployed frontend). Override in deployment via the CORS_ORIGINS env var.
+_DEFAULT_ORIGINS = (
+    "http://localhost:5173,http://127.0.0.1:5173,http://localhost:4173,"
+    "https://sri-28-docuask.static.hf.space"
+)
 ALLOWED_ORIGINS = [
     origin.strip()
     for origin in os.getenv("CORS_ORIGINS", _DEFAULT_ORIGINS).split(",")

frontend/.env.example

@@ -1,7 +1,11 @@
 # Frontend build-time configuration.
 
-# Base URL for the API. Leave UNSET for:
-#   - local dev (Vite proxies /api to the backend), and
-#   - the single-image Hugging Face deploy (API is same-origin under /api).
-# Set it only when hosting the frontend separately from the backend, e.g.:
+# Base URL for the API. Resolution order at runtime:
+#   1. HF Space variable `DOCUASK_API_URL` (set in the Static Space settings) —
+#      preferred for the Hugging Face deploy; changeable without a rebuild.
+#   2. VITE_API_URL below (baked in at build time).
+#   3. "/api" — local dev (Vite proxy) and the single-origin Docker image.
+#
+# Leave UNSET for local dev and the combined image. For split hosting where you
+# want the URL baked in instead of using the HF variable, set it here:
 # VITE_API_URL=https://your-backend.example.com

frontend/src/api.js

@@ -1,6 +1,20 @@
-// In dev, requests go to "/api/*" and Vite proxies them to the backend.
-// In production, set VITE_API_URL to the deployed backend origin.
-export const API_BASE = import.meta.env.VITE_API_URL || "/api";
+// Resolve where the API lives, in priority order:
+//   1. An HF Space variable `DOCUASK_API_URL` (read at runtime — set it in the
+//      Static Space settings so the URL can change without a rebuild).
+//   2. A build-time `VITE_API_URL` (baked in via frontend/.env.production).
+//   3. "/api" — local dev (Vite proxy) and the combined single-origin image.
+function resolveApiBase() {
+  if (typeof window !== "undefined") {
+    const fromHf = window.huggingface?.variables?.DOCUASK_API_URL;
+    if (fromHf) return fromHf.replace(/\/$/, "");
+  }
+  if (import.meta.env.VITE_API_URL) {
+    return import.meta.env.VITE_API_URL.replace(/\/$/, "");
+  }
+  return "/api";
+}
+
+export const API_BASE = resolveApiBase();
 
 /** Extract a human-readable message from a FastAPI error response. */
 async function errorDetail(res) {