# Инструкция: настроить CI-деплой проекта на боксе (для агента-исполнителя)

## Твоя задача
Сделать так, чтобы push в ветку `main` репозитория в Gitea автоматически:
1) собирал фронт (pnpm + vite), 2) собирал Go-бинарь, 3) раскладывал их на боксе и перезапускал сервис.

Раннер и инструменты УЖЕ стоят и работают. Ты только добавляешь workflow-файл в репо,
регистрируешь юнит сервиса и проверяешь деплой.

---

## Факты окружения (проверять не нужно — верны)

- **Раннер:** `box-runner` (Gitea Runner v3.3.1), user-юнит `act-runner.service`, метка `ubuntu-latest` = host-режим.
- **Джобы CI выполняются на хосте бокса от пользователя `homelab`** (не в docker!). Имеют доступ к `~/apps`, `systemctl --user`, локальному docker.
- **PATH внутри джоб:** `~/.local/bin` (node 22, npm, pnpm 11) + `~/apps/go/bin` (go 1.27) + стандартный.
- **Цели деплоя:**
  - статика SPA → `~/apps/hub/dist/` (Caddy `hub.alexey-homelab.duckdns.org` отдаёт её по `/`, SPA-fallback на `/index.html`)
  - Go-бинарь → `~/apps/hub/hub-api`, должен слушать **`127.0.0.1:8484`** (Caddy проксирует `/api/*` туда)
- **Юнит сервиса:** файл `~/srv/hub-api.service` уже создан, но НЕ зарегистрирован (бинарника ещё нет).

---

## Шаги

### Шаг 1. Узнай структуру проекта
Выясни у пользователя (или посмотри в репо):
- где `package.json` (фронт) — ожидается `frontend/`
- где `main.go` (бэк) — ожидается `api/`
Если структура другая — поправь пути в шаблоне workflow (шаг 2).

### Шаг 2. Добавь workflow в репо
Скопируй блок ниже в репо как `.gitea/workflows/deploy.yml`:

```yaml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Build frontend (pnpm + vite)
        run: |
          cd frontend
          pnpm install --frozen-lockfile
          pnpm build

      - name: Build API (Go)
        run: |
          cd api
          CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o hub-api .

      - name: Deploy to box
        run: |
          mkdir -p ~/apps/hub/dist
          cp -r frontend/dist/* ~/apps/hub/dist/
          cp api/hub-api ~/apps/hub/hub-api
          chmod +x ~/apps/hub/hub-api
          systemctl --user restart hub-api
```

ВАЖНО:
- `pnpm install --frozen-lockfile` требует `pnpm-lock.yaml` в репо — убедись, что он закоммичен.
- Если юнит ещё не зарегистрирован (шаг 3 не сделан), последняя строка упадёт — добавь `|| true` временно, пока не сделаешь шаг 3.

### Шаг 3. Зарегистрируй юнит сервиса (один раз, на боксе)
```bash
ln -sf /home/homelab/srv/hub-api.service ~/.config/systemd/user/hub-api.service
systemctl --user daemon-reload
systemctl --user enable hub-api
```
НЕ запускай (`start`) — бинарника ещё нет, юнит упадёт. Он поднимется сам после первого деплоя
(`systemctl --user restart hub-api` в workflow).

### Шаг 4. Проверь джобу
- Сделай push в `main` → открой Gitea UI → репо → вкладка **Actions** → смотри лог джобы.
- Джоба должна пройти зелёной: build → deploy.

### Шаг 5. Проверь деплой
```bash
ls -la ~/apps/hub/                        # dist/ + hub-api на месте
curl -s http://127.0.0.1:8484/api/health  # ответ API (если бинарник жив)
curl -s -o /dev/null -w '%{http_code}\n' https://hub.alexey-homelab.duckdns.org/ \
  --resolve hub.alexey-homelab.duckdns.org:443:127.0.0.1   # 200 = статика отдаётся
```
Если бинарник падает: `journalctl --user -u hub-api -n 30` — смотри ошибку (чаще всего: не тот порт/адрес, отсутствие флага).

---

## Питфоллы

1. **Джобы без docker** (host-метка). Не используй `docker:`-шаги в CI. Если понадобится docker —
   менять метку в `~/apps/act_runner/config.yaml` (`ubuntu-latest:docker://...`) + `systemctl --user restart act-runner` — но это отдельное решение.
2. **Go-бинарь должен слушать `127.0.0.1:8484`** — проверь дефолт/флаг в коде (`:8484`), Caddy уже смотрит туда.
3. **`actions/checkout@v4` скачивается с GitHub** — с бокса работает (не менять на самописный клон без нужды).
4. **pnpm store** кэшируется в `~/.local/share/pnpm` — холодная сборка только первый раз.
5. **Не удаляй и не двигай** `~/apps/act_runner/` (там `.runner` — регистрация раннера) и `~/srv/act-runner.service`.
6. **`systemctl --user restart hub-api` в CI** — юнит должен существовать (шаг 3), иначе джоба упадёт на деплое.