teqo-backup/docs/plans/ops71-runner-self-hosted-github-homeserver-impl.md

# Impl: Runner self-hosted do GitHub no homeserver (deploy do dispatch manual) + CURSOR_API_KEY

Status: aguardando aprovação
Atualizado em: 2026-08-19
Issue: #113
Intenção: o body da Issue #113 (OPS71-INFRA) é a spec — sem plano de intenção separado
Appetite: horas de operação (não é Issue de código — nada de schema/UI/access)

## Leitura da intenção

- **Outcome:** o job `deploy` do `.github/workflows/deploy.yml` (dispatch manual)
  roda no **runner self-hosted do GitHub instalado no homeserver** (labels
  `self-hosted` + `homeserver`), executando `scripts/deploy-homeserver.sh <sha>`
  localmente (sem SSH). O hosted (`verify`) nunca toca o homeserver.
- **O que NÃO negociar:** runner só no `deploy.yml` (nunca no `ci-pr.yml`);
  usuário com docker group + leitura de `~/stack/`; outbound-only (funciona
  atrás do Cloudflare tunnel); registro do runner em infra-solla `STATE.md`.
- **Já validado na sessão (pre-flight):**
  - SSH ao homeserver OK (LAN `192.168.15.142`, user `fsolla`).
  - `fsolla` tem `docker` no groups + `sudo`; lê `~/stack/teqo-1313.env` e
    `~/stack/.env` (modo 600, dono = fsolla). Arch `x86_64` → tarball linux-x64.
  - **Runner ainda NÃO existe** no homeserver (sem `~/actions-runner`, sem unit
    systemd do runner; o `runner-watch.*` é outra coisa — WoL/shutdown da
    workstation).
  - **PAT do OPS71 funciona** (local, `~/.bashrc`): `GET /repos/fsolla/teqo` 200
    e `POST …/actions/runners/registration-token` 201 → admin no repo OK.
  - Versão estável atual do runner: **v2.336.0** linux-x64, 226 MB,
    sha256 `04cf0be1aff4c3ec3554466c39124ca250e3effd8873bb7e8d68535aa9505d5d`
    (digest da API de releases do GitHub).
  - **Linger do homeserver já ativo** (`loginctl show-user fsolla` →
    `Linger=yes`) → systemd **user** funciona sem sudo (o `runner-watch` já é
    user service persistente lá — prova do padrão).
  - Workspace `~/teqo-deploy` existe mas ainda aponta origin → Forgejo
    (`http://localhost:3000/…`): o `set-url` idempotente do
    `deploy-homeserver.sh` re-aponta para `TEQO_REPO_URL` (GitHub) no primeiro
    deploy — nada a fazer, mas é o que o log do primeiro deploy deve mostrar.

## Abordagem recomendada

Sequência **operacional no homeserver** (nenhum commit no repo teqo — o código
do OPS71 já foi mergeado; o único artefato commitado desta Issue é o registro no
`STATE.md` do infra-solla, repo separado):

1. **Download** (homeserver, `~/actions-runner`): tarball v2.336.0 linux-x64 da
   release oficial, **sha256 conferido** contra o digest da API de releases.
2. **Registration token** (workstation, PAT local): `POST
/repos/fsolla/teqo/actions/runners/registration-token` (TTL 1 h — gerar e
   configar na sequência, um único passo encadeado).
3. **config.sh** (homeserver, user fsolla):
   `./config.sh --url https://github.com/fsolla/teqo --token <token> --labels
self-hosted,homeserver --name teqo-1313-runner --work _work`.
4. **svc.sh como systemd USER** (`./svc.sh install` sem root → unit
   `~/.config/systemd/user/actions.runner.fsolla-teqo-1313-runner.service`) +
   `systemctl --user enable --now …` (start). Linger já ativo → persiste sem
   login; roda como fsolla (docker + `~/stack` envs).
5. **Verificação do runner**: `systemctl --user status …` ativo; runner listado
   em `GET /repos/fsolla/teqo/actions/runners` como online.
6. **Registro em infra-solla** (`~/Code/infra-solla/STATE.md`): entrada na
   seção do Teqo + nota na tabela de topologia (runner GitHub no homeserver,
   labels, dir, systemd user) — e no runbook `docs/ops/teqo-1313-deploy.md` do
   teqo (a tabela "Onde roda cada coisa" já o menciona prospectivamente; só
   confirmar o texto com o estado real). Changelog `docs/changelog/2026-08-20-ops71-infra.md` + `pnpm changelog:build`.
7. **Aceite (verificação ao vivo)**: dispatch manual do `deploy.yml` (ref main)
   → `verify` full verde → job `deploy` roda no runner do homeserver → log com
   o `set-url` do workspace (Forgejo → GitHub) + smoke ok → **segundo dispatch
   do mesmo SHA** → guard "already deployed".

**Decisões:**

- **systemd user + linger (já ativo) vs. `svc.sh install` via root:** user — sem
  senha sudo interativa, mesmo padrão do `runner-watch` (persistência provada no
  próprio homeserver); o unit system-level não adicionaria nada (o unit user
  roda com `User=fsolla` de qualquer forma).
- **`~/actions-runner` + workdir `_work`:** convenção oficial; `~/teqo-deploy`
  permanece como workspace do deploy (o script seta `TEQO_REPO_URL` nele).
- **Sem mudanças em código/workflows:** `runs-on: [self-hosted, homeserver]`
  já está no `deploy.yml`; o `deploy-homeserver.sh` já tem o `set-url`
  idempotente. O runner vem do GitHub com o token de registro — sem secrets
  novos no repo (o repo é público; as envs de produção ficam no homeserver).

**Rejeitadas:**

- **`svc.sh install` como root** — exigiria sudo interativo; nada ganho sobre o
  unit user (mesmo usuário efetivo, linger já garante auto-start no boot).
- **Rodar o runner em container/docker** — complexidade extra; o padrão oficial
  do GitHub é o binário com svc; o runner-watch local prova o user service.
- **Instalar agora o helper `archive-cursor-agent` / criar o secret
  `CURSOR_API_KEY` no GitHub** — item secundário da Issue, dormente (pool morto,
  OPS65): a key não existe no ambiente; fica **registrado como pendência** no
  fechamento (pedir a key ao humano quando quiser reativar o helper), sem ação
  agora.

## Fases verificáveis

1. Runner baixado + sha256 conferido.
2. Runner configurado (`.runner` + `.credentials` no `~/actions-runner`),
   labels corretas, nome `teqo-1313-runner`.
3. Unit systemd user ativo e **persistente** (`systemctl --user is-enabled …`),
   runner online na API do GitHub.
4. `STATE.md` (infra-solla) + runbook + changelog registrados.
5. Dispatch manual de validação (verify → deploy → already-deployed no segundo
   dispatch) — **aceite final, exige o humano** (dispara no GitHub UI).

## Rabbit holes / Não escopo (engenharia)

- Não re-engenharia do `deploy-homeserver.sh` (fluxo compose/migrate intacto).
- Não mexer no stack/registry/env do homeserver.
- Não criar secret `CURSOR_API_KEY` (dormente — só com a key do usuário).
- Não editar o `ci-pr.yml` nem a branch protection.

## Riscos e mitigação

- **Token de registro expira em 1 h** → o `config.sh` roda na mesma sequência
  do POST (script encadeado da workstation → homeserver).
- **`svc.sh install` gerar unit system em vez de user** (se detectar root):
  rodar sem sudo garante o user unit; se algo criar system unit, desfazer com
  `svc.sh uninstall` e repetir como user.
- **Runner offline no dispatch** → falha conhecida já documentada no runbook
  ("job deploy nunca roda / runner offline"): checar `systemctl --user status`,
  o runner-watch local não cuida deste runner (não é o forgejo-runner).
- **verify full ~50 min hosted antes do deploy** → aceite da Issue é um ciclo
  completo; nada do homeserver é tocado até `verify` verde.
- **Rollback**: `~/actions-runner/./svc.sh uninstall` + `rm -rf ~/actions-runner`
  (desregistra no GitHub); o deploy volta a ficar indisponível até o runner ser
  religado — comportamento conhecido, documentado no runbook.

## Aceite de engenharia

- [ ] Aceite de produto da intenção coberto (deploy self-hosted no homeserver,
      verify hosted nunca toca o homeserver)
- [ ] Runner instalado como fsolla (docker + `~/stack`), systemd user com
      linger, outbound-only
- [ ] Registrado em infra-solla `STATE.md` + runbook + changelog
- [ ] Validação ao vivo: dispatch manual → deploy no runner → "already
      deployed" no segundo dispatch