Pular para conteúdo

Deploy da plataforma (produto)

Este documento é sobre o deploy do produto (app.garantora.com.br, box srv01, stack infra/prd). Para o deploy do site de documentação, ver documentation-platform.md.

Comando

/ship

É o único caminho para a produção — nunca à mão na box, e sempre pedido de quem decide, nunca iniciativa de um agente. O skill vive em .claude/skills/ship/SKILL.md (spec 0030), roda na máquina de quem chama e orquestra a box por SSH. Não confunda com /devremote-rebuild, que é o dev.garantora.com.br.

O que ele faz, em ordem

  1. Pré-voo (não toca a produção) — git fetch, compara o main local, o origin/main e o HEAD que está no ar, e lista commits e migrations pendentes. Deploya origin/main: recusa se o main local estiver à frente (não faz push por você) e para se a produção já estiver em origin/main.
  2. Nota de versão (spec 0043) — todo deploy publica uma versão semver, com a nota de novidades em apps/web/src/versoes/X.Y.Z.md, que o produto exibe num painel. Sem a nota em origin/main, o pré-voo recusa (exit 5): o skill propõe o número, grava um rascunho com rascunho-nota.sh, e a nota é reescrita para quem usa o produto, commitada e empurrada antes de rodar o /ship de novo. A nota é pública — vai no bundle servido até na tela de login: nada de nome de cliente, valor ou pessoa.
  3. Gate humano — mostra commits, migrations, a versão e o texto inteiro da nota, e espera um "sim" explícito.
  4. Deploy na box — git pull --ff-only → make up (rebuild e recriação de api, worker, web e demais serviços, com a versão como build arg das imagens) → backup antes de migrar (make backup → make migrate, só quando há migration) → make seed sempre, com ou sem migration. O boot da API não aplica migrations nem seed (RN7 da spec 0028), então esses passos são do deploy.
  5. Verificação de fora — https://app.garantora.com.br/api/v1/health responde {"status":"ok","db":"ok"} com o version publicado, a raiz responde 200 com TLS válido, e o HEAD da box bate com origin/main.
  6. Tag vX.Y.Z — criada e empurrada só depois da verificação passar. É a única escrita no remoto que o fluxo faz sem pedido separado (o "sim" do gate é o pedido).

Por que o seed roda sempre. Permissão nova é dado de seed, não de schema — entra sem migration nenhuma. Sem o passo, a feature sobe com o código novo e o banco sem a permissão, e o papel que ela habilita toma 403 com o botão escondido. O seed também retira dos papéis de sistema o que o código não declara mais (spec 0035); perfis customizados por tenant não são tocados.

Passo a passo técnico e diagrama de sequência em ../architecture/deployment.md; os códigos de saída do pré-voo e o roteiro completo, no próprio SKILL.md.

O worker e o Redis

A produção roda, além de api e web, o worker da fila (arq sobre Redis, spec 0050) — mesma imagem da api, com outro command —, e o redis. Os três ambientes têm os dois: no local, make worker-dev sobe o worker e o Redis vem do make local-up; no dev-remote o worker é container e o Redis é serviço nativo do host; na produção, os dois são containers de infra/prd. O worker executa a consulta ao bureau de crédito e os jobs agendados (o das 6h, que purga o payload bruto vencido e sincroniza extrato e preços das consultas, e o das 7h, que marca cobranças vencidas). API no ar com worker parado não falha: esses processos simplesmente não acontecem — confira make ps na box quando algo agendado não aconteceu.

Rollback

O /ship não reverte sozinho.

  1. Código — na box, cd /opt/garantora && git reset --hard <commit-anterior> e cd infra/prd && make up.
  2. Schema, se a versão ruim trouxe migration — duas saídas:
  3. alembic downgrade (pelo container da api, com o código ainda novo, que é quem tem o script da migration) antes de trocar o código, para não deixar código velho contra schema novo; ou
  4. restaurar o dump que o /ship gerou antes da migration: docker compose exec backup ls -lh /backups para achá-lo, depois make restore FILE=<dump>.sql.gz (assume banco compatível ou vazio — ver infra/prd/README.md).
  5. Confirmar curl https://app.garantora.com.br/api/v1/health e a raiz pública.

O downgrade de toda migration é obrigatório desde a spec 0028 exatamente para este caminho — exercitá-lo faz parte do fechamento de qualquer trabalho com migration.

Backup

infra/prd roda um serviço backup dedicado (pg_dump em loop sobre o volume postgres_backups), e o /ship dispara make backup antes de qualquer migration. Ver infra/prd/backup/backup.sh e infra/prd/README.md ("Backup e restore") para o procedimento de restauração.