docs/huggingface-space-deploy_en.md

# Hugging Face Space deploy

Target deployment flow:

```text
Corporate GitLab repository
        ↓ GitLab CI
Private Hugging Face Docker Space
        ↓ CPU Basic / Free
HiveTrace Leaderboard
```

## Hugging Face Space

The Space is created manually once.

Recommended settings:

- Visibility: `Private`
- SDK: `Docker`
- Hardware: `CPU Basic` / free
- App port: `5173`

The project `README.md` already contains the Space frontmatter:

```yaml
---
title: HiveTrace Leaderboard
emoji: 🛡️
colorFrom: green
colorTo: indigo
sdk: docker
app_port: 5173
pinned: true
---
```

## Runtime secrets and variables in Hugging Face

Add the runtime secret in Space Settings:

```text
HF_TOKEN=hf_...
```

This token is required by the app to read the private Hugging Face bucket. Do not expose it as
a `PUBLIC_*` variable and do not commit it to the repository.

Variables:

```text
HF_BUCKET_ID=hivetrace/leaderboard_frontend_v2
HF_BUCKET_PREFIX=latest
HF_BUCKET_CACHE_TTL_MS=300000
HF_BUCKET_REQUEST_TIMEOUT_MS=60000
HF_BUCKET_REQUEST_RETRIES=2
```

Optional:

```text
HF_BUCKET_ENDPOINT=https://huggingface.co
```

## GitLab CI variables

Add the following CI/CD variables in the corporate GitLab project:

```text
HF_USERNAME=<huggingface-user-or-service-account-name>
HF_SPACE_TOKEN=<huggingface-write-token-for-space-repo>
HF_SPACE_REPO=<namespace>/<space-name>
```

Example:

```text
HF_SPACE_REPO=hivetrace/guard-leaderboard
```

`HF_SPACE_TOKEN` must have write access to the Space repository.

Important: keep `HF_SPACE_TOKEN` and the runtime `HF_TOKEN` used for bucket reads as separate
tokens.

In GitLab, mark `HF_SPACE_TOKEN` as a masked/protected variable.

## Deploy flow

`.gitlab-ci.yml` runs two stages:

1. `validate`
   - `pnpm install --frozen-lockfile`
   - `pnpm check` (generates Paraglide output internally)
   - `pnpm build`

2. `deploy:huggingface`
   - runs only on the `prod` branch
   - pushes the current commit to the private Hugging Face Space repository
   - uses force push because the Hugging Face Space repository is a deploy repository
   - the Space automatically rebuilds the Docker image after the push

## Production branch

Production deployment runs only from the `prod` branch.

Typical flow:

```bash
git checkout prod
git merge main
git push origin prod
```

After the push to `prod`, GitLab CI runs validation and then sends this commit to the `main`
branch of the Hugging Face Space repository.

## Local Docker smoke test

Before the first deployment, it is useful to test the Docker image locally:

```bash
docker build -t hivetrace-leaderboard .
docker run --rm -p 5173:5173 \
  -e HF_TOKEN=hf_... \
  -e HF_BUCKET_ID=hivetrace/leaderboard_frontend_v2 \
  -e HF_BUCKET_PREFIX=latest \
  hivetrace-leaderboard
```

After startup, open:

```text
http://127.0.0.1:5173/
```