docs/huggingface-space-deploy_ru.md

# Hugging Face Space deploy

Целевая схема:

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

## Hugging Face Space

Space создается вручную один раз.

Рекомендуемые настройки:

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

В `README.md` проекта уже есть 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

В Space Settings нужно добавить runtime secret:

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

Этот токен нужен приложению для чтения приватного Hugging Face bucket. Его нельзя делать
`PUBLIC_*` переменной и нельзя коммитить в репозиторий.

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

Опционально:

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

## GitLab CI variables

В корпоративном GitLab нужно добавить CI/CD variables:

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

Пример:

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

`HF_SPACE_TOKEN` должен иметь право записи в Space repository.

Важно: `HF_SPACE_TOKEN` и runtime `HF_TOKEN` для чтения bucket лучше держать разными
токенами.

`HF_SPACE_TOKEN` в GitLab лучше пометить как masked/protected variable.

## Deploy flow

`.gitlab-ci.yml` делает два этапа:

1. `validate`
   - `pnpm install --frozen-lockfile`
   - `pnpm check` (внутри генерирует Paraglide output)
   - `pnpm build`

2. `deploy:huggingface`
   - срабатывает только на ветке `prod`
   - пушит текущий commit в private Hugging Face Space repository
   - использует force push, потому что Hugging Face Space является deploy-репозиторием
   - Space автоматически пересобирает Docker image после push

## Production branch

Продакшн-деплой запускается только из ветки `prod`.

Типовой flow:

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

После push в `prod` GitLab CI выполнит validate-этап и затем отправит этот commit в
ветку `main` Hugging Face Space repository.

## Local Docker smoke test

Перед первым deploy желательно локально проверить Docker image:

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

После запуска открыть:

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