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

Твоя задача

Сделать так, чтобы push в ветку main репозитория в Gitea автоматически:

собирал фронт (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:

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. Зарегистрируй юнит сервиса (один раз, на боксе)

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. Проверь деплой

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 — смотри ошибку (чаще всего: не тот порт/адрес, отсутствие флага).

Питфоллы

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

5.7 KiB Raw Blame History