SPACES.md

Deploy to Hugging Face Spaces

This app needs a Docker Space (Node broker + static WebGPU UI on one origin with COOP/COEP headers).

Space: apssouza22/webgpu-cluster
Live app: apssouza22-webgpu-cluster.hf.space

---

Deploy a new version

Run these steps from the project root whenever you change frontend or broker code.

1. Install dependencies (if needed)

npm install

Use the project .npmrc (public npm). Do not regenerate package-lock.json against a private registry.

2. Build the Space UI

npm run build:space

This writes the production bundle to docs/ with base path / (required for the Space URL).
Do not use npm run build for Spaces — that target uses /webgpu-video-ai/ for GitHub Pages.

3. (Optional) Test locally

PORT=7860 npm start

Open http://localhost:7860/ and confirm the host page and /health work.

4. Log in to the Hub

hf auth whoami   # skip if already logged in
hf auth login    # one-time; needs a write token

5. Upload to the Space

hf upload apssouza22/webgpu-cluster . . \
  --repo-type space \
  --exclude ".git/*" \
  --exclude "node_modules/*" \
  --exclude ".idea/*" \
  --exclude ".claude/*" \
  --commit-message "Describe your change here"

HF rebuilds the Docker image automatically (usually 1–3 minutes).

6. Verify the deployment

# Build status
hf spaces info apssouza22/webgpu-cluster

# Build logs (if something failed)
hf spaces logs apssouza22/webgpu-cluster --build --tail 50

When runtime.stage is RUNNING:

curl -s https://apssouza22-webgpu-cluster.hf.space/health
# → {"status":"ok"}

Open apssouza22-webgpu-cluster.hf.space, start a host, and run a detect request from monitor.html.

What gets deployed

Uploaded	Role
docs/ (from build:space)	Static UI + workers
server/, shared/	Node broker
Dockerfile, package.json, package-lock.json, .npmrc	Container build

The image does not run Vite; it only serves prebuilt docs/. Always run step 2 before upload.

---

First-time setup

1. Log in

hf auth login

Create a token at huggingface.co/settings/tokens (write access).

2. Create the Space (once)

Only needed if the Space does not exist yet:

hf repos create apssouza22/webgpu-cluster \
  --type space \
  --space-sdk docker \
  --exist-ok

Then follow Deploy a new version above.

Use the Space

1. Open apssouza22-webgpu-cluster.hf.space
2. Pick a host id and click Start hosting (WebGPU runs in the browser tab)
3. Open /monitor.html for curl examples
4. Call the API on the same URL, e.g.:

curl -X POST 'https://apssouza22-webgpu-cluster.hf.space/v1/detect' \
  -H 'Content-Type: application/json' \
  -d '{
    "host": "my-gpu-node",
    "image_url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/coco_sample.png",
    "threshold": 0.5
  }'

Local Docker test

docker build -t gpu-video-cluster .
docker run --rm -p 7860:7860 gpu-video-cluster

Then open http://localhost:7860/

Notes

• WebGPU runs in the visitor’s browser (Chrome/Edge desktop). The Space container only hosts the broker and static files.
• First model load downloads weights from the Hub into the browser cache.
• GitHub Pages builds use npm run build (base /webgpu-video-ai/). Spaces use npm run build:space (vite build --mode space, base /) via the Dockerfile.