commit 2

2026-08-29 10:29:48 +05:00
parent eaa9a7bef2
commit 069b51a84c
16 changed files with 949 additions and 471 deletions
@@ -0,0 +1,105 @@
+# Инструкция: настроить 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), иначе джоба упадёт на деплое.
+