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](https://huggingface.co/spaces/apssouza22/webgpu-cluster)  
**Live app:** [apssouza22-webgpu-cluster.hf.space](https://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)

```bash
npm install
```

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

### 2. Build the Space UI

```bash
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

```bash
PORT=7860 npm start
```

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

### 4. Log in to the Hub

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

### 5. Upload to the Space

```bash
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

```bash
# 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`:

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

Open [apssouza22-webgpu-cluster.hf.space](https://apssouza22-webgpu-cluster.hf.space/), start a host, and run a detect request from [monitor.html](https://apssouza22-webgpu-cluster.hf.space/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

```bash
hf auth login
```

Create a token at [huggingface.co/settings/tokens](https://huggingface.co/settings/tokens) (write access).

### 2. Create the Space (once)

Only needed if the Space does not exist yet:

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

Then follow [Deploy a new version](#deploy-a-new-version) above.

## Use the Space

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

```bash
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

```bash
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.