camilafagundesandClaude Opus 5
5b11496cd9
Havia dois runbooks sobrepostos, escritos para o piloto, e nenhum documento do ambiente de homologação. - `20-homologacao-runbook.md` consolida os dois e cobre DNS, TLS, Nginx, Supabase de homologação, banco com a decisão do shim, bucket privado, containers, worker, observabilidade, flag, rollback, diagnóstico e smoke. Os dois runbooks antigos ficam no repositório marcados como histórico, preservando o registro das decisões. - Rollback de imagem com comandos: identificar o que está no ar, listar tags, desligar a flag antes de trocar, subir só web e worker com `--no-deps`, conferir saúde, religar a flag. As migrations de segurança — RLS e auditoria append-only — estão declaradas sem caminho de volta: desfazê-las afrouxa o isolamento entre workspaces, então um rollback que precise disso está errado por definição. - `21-checklist-validacao.md` separa o que foi executado do que depende de infraestrutura, com a evidência de cada item e a tabela dos quatro defeitos encontrados. Nada está marcado PASS por inspeção de código. - ADR 0007 registra o ambiente lógico e a autenticação de homologação, com as alternativas descartadas e o motivo. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
56 lines
2.8 KiB
Markdown
56 lines
2.8 KiB
Markdown
# Deploy e operação
|
|
|
|
> **Histórico.** Este runbook foi escrito para o piloto, antes do ambiente de
|
|
> homologação existir. Não siga este arquivo. O procedimento vigente está em
|
|
> [`20-homologacao-runbook.md`](20-homologacao-runbook.md), que consolida este e
|
|
> o `16-pilot-deployment-runbook.md`. Mantido para registro das decisões.
|
|
|
|
|
|
## Ordem
|
|
|
|
1. Conferir envs sem colar segredo no repositório.
|
|
2. `npm run migrate` na `DATABASE_URL` do ambiente.
|
|
3. Subir a aplicação com a flag ainda desligada.
|
|
4. Subir `npm run worker` e o Redis do ambiente.
|
|
5. Confirmar bucket privado. Não criar bucket público.
|
|
6. Smoke test no workspace piloto e só então `npm run flag -- <workspace_id> on`.
|
|
|
|
## Variáveis
|
|
|
|
| Nome | Uso |
|
|
| --- | --- |
|
|
| `NEXT_PUBLIC_SUPABASE_URL` | Auth no browser/servidor |
|
|
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Chave pública do Auth |
|
|
| `SUPABASE_SERVICE_ROLE_KEY` | Storage no servidor. Nunca `NEXT_PUBLIC_` |
|
|
| `SUPABASE_STORAGE_BUCKET` | Bucket privado |
|
|
| `DATABASE_URL` | PostgreSQL. Obrigatório em produção |
|
|
| `REDIS_URL` | Lock. Sem ela o processamento recusa iniciar |
|
|
| `SENTRY_DSN` / `NEXT_PUBLIC_SENTRY_DSN` | Observabilidade |
|
|
| `SENTRY_ENVIRONMENT` / `SENTRY_RELEASE` | Ambiente e release |
|
|
| `ELO_PRO_LOGIN_URL` | Login central |
|
|
| `SPREADSHEET_TEMP_TTL_SECONDS` | Retenção. Obrigatório em produção; valor de produto ainda aberto |
|
|
| `ADAPTER_JOB_MODE` | `worker` em produção, `inline` em desenvolvimento |
|
|
| `ADAPTER_DEV_AUTH` | Só fora de produção |
|
|
| `ADAPTER_DEV_AUTH_SECRET` | Assina o cookie local. Não é senha de usuário |
|
|
|
|
O cookie de workspace lido pela aplicação chama-se `elo_pro_workspace_id`.
|
|
|
|
## Rollback
|
|
|
|
- Aplicação: voltar o deploy anterior.
|
|
- Flag: `npm run flag -- <workspace_id> off`.
|
|
- Schema: `migrations/down/0002_spreadsheet_adapter_down.sql` remove só tabelas do módulo.
|
|
- Jobs: parar o worker. Jobs `queued` não avançam. Jobs `processing` sem lock viram `INTERRUPTED` na próxima varredura.
|
|
|
|
## Smoke
|
|
|
|
Login Elo Pro sem segunda senha; workspace piloto com flag ligada; upload de modelo; fonte; aba ou cabeçalho se preciso; mapeamento; prévia; download XLSX, CSV e PDF; workspace sem flag recebe bloqueio; download sem sessão recebe 401.
|
|
|
|
## Runbook
|
|
|
|
- Job travado em `processing`: confirmar se o lock Redis ainda existe. Se expirou, o worker marca `INTERRUPTED`. O usuário pode tentar de novo.
|
|
- Redis indisponível: APIs de leitura seguem; processamento responde `REDIS_UNAVAILABLE` e não grava saída.
|
|
- Storage indisponível: upload falha com `STORAGE_FAILURE` ou 503 e não deixa modelo sem arquivo.
|
|
- Migration parcial: `schema_migrations` só registra arquivo aplicado por completo. Reexecutar `npm run migrate` continua do próximo arquivo. Não editar migration já aplicada.
|
|
- Limpeza: `npm run cleanup` apaga blobs em chaves `/tmp/` expiradas e não mexe em `/models/`.
|