- ci.yml: on push removido; schedule */30 + workflow_dispatch - job check (host, sem pnpm): SHA deployado via ssh + diff + classificador .dockerignore (scripts/ci-classify-production.mjs, lib/dockerignore.mjs) - suite fail-open no gate; deploy duplo-gated (checks + production) - deploy-homeserver.sh: guard 'already deployed' (idempotente) - agent-pool.yml removido; pool dormente - specs: dockerignoreMatch, ciClassifyProduction, pins ciSkipInvariants/deployScript - docs: runbook, AGENTS.md, AGENT-OPS.md, changelog
12 KiB
Runbook: deploy do site 1313 no homeserver (OPS53, janela OPS65)
O deploy de produção é uma etapa do CI (ci.yml no Forgejo): mergir em main
com a suite verde publica o site em jorgesolla1313.com.br — sem passo manual,
em até 30 min após o merge.
Gatilho e fluxo
git pushparamain(via PR merge) — oci.ymlnão dispara mais a cada push: roda por janela fixa de 30 min (schedule */30) ou viaworkflow_dispatch(deploy manual, imediato, sempre full suite).- Job
check(gate barato, host, sem pnpm): lê o SHA deployado de~/stack/docker-compose.ymlno homeserver viasshe classifica "mudança de produção" com o.dockerignorecomo fonte da verdade (o que não entra na imagem não justifica build novo;docs/,.agents/,.env*viram skip;scripts/,tests/,.forgejo/contam como produção — conservador, qualquer dúvida roda a suite).- Sem mudança de produção → suite e deploy skipped; run verde.
- Gate com erro (ssh/SHA ilegível) → fail-open: suite roda; deploy fica para a próxima janela (auto-cura em ≤30 min).
- Com mudança de produção: suite completa verde (static/int/build/e2e/checks).
- Job
deploy(runs-onhost, na workstation) rodassh homeserver "bash -s -- <sha>" < scripts/deploy-homeserver.sh. O script é idempotente: se o compose já referencia o SHA (ex.: dispatch duplicado), sai verde "already deployed" sem rebuild. - O script, no homeserver: guarda de HEAD (
mainremoto == SHA do job, senão skip) →flock(serializa) → guard "already deployed" → build da imagem standalone + migrator (BuildKit, secrets do~/stack/teqo-1313.env,--network hostcom proxy socatteqo-1313-build-proxynastack_defaultpara o build alcançar opostgres— o proxy é criado idempotentemente pelo script) → push emlocalhost:5000→ swap dos tags de imagem no~/stack/docker-compose.yml(backup antes) → migrations (docker compose --profile maintenance run --rm teqo-1313-migrate </dev/null) →docker compose up -d teqo-1313→ healthcheck → smoke (/,/campanha/login,/admin, barreira 307, WebAuthn login-options,api/revalidatecom o secret real). - Falha = job vermelho no commit; nada é publicado pela metade.
Onde roda cada coisa
| Máquina | Papel |
|---|---|
| workstation (16c/61GB) | runner Forgejo (workstation-runner); job deploy roda no host (chave SSH ~/.ssh/id_ed25519 → ssh homeserver) |
| homeserver (8c/16GB) | todo o stack (~/stack/docker-compose.yml): postgres teqo_1313, forgejo, registry localhost:5000, cloudflared, teqo-1313 na 127.0.0.1:1313; workspace ~/teqo-deploy (clone do Forgejo local) |
Segredos não ficam no Forgejo: o script sourceia ~/stack/teqo-1313.env e
~/stack/.env (chmod 600) no próprio homeserver. Nenhum secret novo em
Settings → Actions.
Rollback
A imagem anterior continua local e no registry (localhost:5000/teqo-1313:<sha>
— o registry nunca deleta). O compose anterior fica em
~/stack/docker-compose.yml.pre-<sha-do-deploy-que-falhou>.
ssh homeserver
cd ~/stack
# 1. apontar o compose de volta para o SHA anterior (o que estava rodando):
# o backup do deploy que falhou é o compose com os tags antigos
ls docker-compose.yml.pre-* # escolha o anterior ao deploy ruim
cp docker-compose.yml.pre-<sha-anterior> docker-compose.yml
# 2. a imagem antiga ainda está local; se não, puxe do registry:
docker pull localhost:5000/teqo-1313:<sha-anterior>
docker tag localhost:5000/teqo-1313:<sha-anterior> teqo-1313:<sha-anterior>
# 3. subir:
docker compose up -d teqo-1313
Caveat: uma migration de schema aplicada no passo de migrate não é desfeita pelo rollback (Payload é append-only). Código velho sobre schema novo pode se comportar mal — o caminho primário minimiza essa janela (migrate só roda após build+push ok; rollout só após migrate ok).
Falhas conhecidas
| Sintoma | Causa | Tratamento |
|---|---|---|
| Job verde sem deploy ("stale run") | Push mais novo venceu; o deploy antigo saiu da fila | Nada a fazer — o run do SHA novo deploya |
| Job verde sem deploy ("already deployed") | O compose do homeserver já referencia o SHA do job (ex.: workflow_dispatch duplicado da mesma HEAD) |
Nada a fazer — o site já roda esse SHA. Forçar rebuild da MESMA HEAD não é suportado via dispatch: edite o tag da imagem no compose (image: teqo-1313:<sha>-rebuild) e docker compose up -d, ou espere um commit novo |
Gate check falha (ssh homeserver / SHA ilegível) |
Tailnet fora ou compose ilegível | Fail-open: suite roda; deploy espera a próxima janela (auto-cura em ≤30 min se houver mudança de produção). Se persistir, checar ssh homeserver da workstation |
Todo job docker quebra com exec: "node": executable file not found in $PATH |
runner.envs.PATH do ~/.forgejo-runner/config.yaml (workstation) com paths só de host (nvm/bun) — o container perde o node do toolcache (/opt/acttoolcache); edição do config exige o toolcache primeiro (ver comentário no próprio config) |
Corrigir o PATH no config (toolcache primeiro — ver comentário no próprio arquivo) + systemctl --user restart forgejo-runner (incidente 2026-08-17) |
| Deploy para logo após o migrate ("Done." e nada mais, EXIT=0) | docker compose run anexa stdin por padrão — o container consome o resto do script que vai no pipe do bash -s; o bash chega a EOF e termina sem rodar o rollout |
O script já usa < /dev/null no run --rm do migrate (não remover); sintoma visto 2026-08-17 no primeiro deploy |
Build falha: network mode "stack_default" not supported by buildkit |
BuildKit (drivers docker e docker-container) recusa rede bridge custom no --network |
O script builda com --network host + proxy socat teqo-1313-build-proxy (na stack_default, publicado em 127.0.0.1:5433, criado idempotentemente com restart: unless-stopped) + DATABASE_URL reescrita para o loopback |
| Build OOM no homeserver | Laptop 8c/16GB com o stack ativo (~12GB livres medidos) | Re-dispatch; se recorrente, item futuro: build na workstation com túnel |
checkout@v5 falha no job host |
Label host do act_runner | Fallback: baixar o script direto do Forgejo (curl -s https://git.solla.dev/fsolla/teqo/raw/branch/main/scripts/deploy-homeserver.sh) |
| Migrate falha | Drift/erro de schema | Job vermelho; site segue no container antigo; corrigir e re-mergear |
| Smoke falha pós-up | Regressão de runtime | Rollback automático (restore + up -d) + job vermelho; investigar |
Segurança (decisão deliberada)
- O job
deployusaruns-on: host— executa comofsollana workstation. Está apenas noci.yml(push emmain+ dispatch), nunca noci-pr.yml.mainsó anda por PR mergeado com suite verde. Fork-PRs não disparam workflows no Forgejo (default off — verificado). - Segredos nunca ecoados: sem
set -x, senhas via--password-stdin/ build-secrets; envs só no homeserver.
Referências
scripts/deploy-homeserver.sh— o script remoto (fonte da verdade do fluxo)docs/plans/ops53-ci-deploy-homeserver*.md— intenção e decisões- infra-solla:
STATE.md,plano-infra-final.md§"Arquitetura de deploy"