106 lines
5.7 KiB
Markdown
106 lines
5.7 KiB
Markdown
# Инструкция: настроить 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), иначе джоба упадёт на деплое.
|
|
|