Pular para o conteúdo principal

Runbook

Introdução ao documento​

Este runbook descreve os procedimentos operacionais comprováveis no repositório para executar, empacotar, publicar e recuperar a aplicação. O foco está no que é acionável com base em scripts, pipeline, Docker e Helm realmente versionados aqui.

Fato observado

  • A aplicação é executada localmente por scripts npm, por contêiner com docker-compose e em ambiente remoto por pipeline GitHub Actions + Helm.
  • O deploy remoto publica imagens Docker tagueadas por branch normalizada e por github.sha, e instala a aplicação em namespaces Kubernetes distintos.

Evidências:

Versionamento​

Este documento deve ser atualizado quando houver mudança em:

  • scripts de execução local, build ou testes;
  • estratégia de imagem Docker;
  • pipeline de build e deploy;
  • chart Helm, secrets, probes ou namespaces de destino.

Evidências:

Referencial teórico​

Este runbook foi montado a partir de três fontes operacionais do próprio repositório:

  • scripts de aplicação (package.json);
  • empacotamento local e em contêiner (Dockerfile, docker-compose.yml, compose.sh);
  • automação de entrega (.github/workflows/ci-cd-pipeline.yaml, helm/, kubernetes/).

Inferência controlada

  • Como não há documentação externa versionada de SRE neste workspace, o procedimento operacional mais confiável é o que reproduz o pipeline e os manifests locais.

Evidências:

Execução local​

Pré-requisitos observados​

Fato observado

  • O repositório expõe execução local por npm.
  • Existe um .env.example com variáveis para auth, WordPress, WhatsApp, Datadog, AMEI e metadados.
  • Existe uma opção de execução em contêiner via docker-compose, usando .env e mapeando a aplicação para 3010:3000.

Evidências:

Procedimento com npm​

  1. Criar .env a partir de .env.example.
  2. Instalar dependências com o gerenciador escolhido pelo time.
  3. Executar npm run dev para ambiente de desenvolvimento.
  4. Executar npm run test:unit para testes unitários.
  5. Executar npm run build para validar build de produção.
  6. Executar npm run start para subir a build local.

Evidências:

Procedimento com contêiner​

  1. Garantir um arquivo .env no diretório do projeto.
  2. Garantir que a rede externa dhedalos-network exista no host Docker.
  3. Executar docker-compose up --build -d ou usar compose.sh.
  4. Acessar a aplicação na porta 3010.

Evidências:

Observações de build/runtime local​

Fato observado

  • O Dockerfile usa pnpm install --frozen-lockfile, pnpm run build e pnpm prune --prod.
  • A imagem final roda node server.js em modo standalone, com NODE_ENV=production, PORT=3000, UV_THREADPOOL_SIZE=4 e NODE_OPTIONS com GC exposto.

Evidências:

Deploy​

Pipeline comprovado​

Fato observado

  • O job build roda em ubuntu-latest, baixa um .env de S3 e publica a imagem no registry.
  • A imagem é enviada com duas tags: branch normalizada e github.sha.
  • main faz deploy em piloto-dhedalos-ecosystem no cluster oke-we-002.
  • release faz deploy em essencia-ecosystem e dhedalos-ecosystem no cluster oke-we-001.

Evidências:

Comando de deploy observado no pipeline​

helm dependency build helm
helm upgrade --install --create-namespace -n <namespace> <release-name> helm \
  -f kubernetes/<cluster>/<namespace>/values.yaml \
  --set image.repository=<registry>/<repository>/<app> \
  --set image.tag=<github-sha>

Evidências:

Ambientes comprovados​

FluxoBranchClusterNamespaceHostname(s)
Pilotomainoke-we-002piloto-dhedalos-ecosystemonboarding.stg.dhedalos.com
Essênciareleaseoke-we-001essencia-ecosystemcadastro.essencia.dhedalos.com, onboarding.essencia.dhedalos.com
Produçãoreleaseoke-we-001dhedalos-ecosystemcadastro.sebraeingresse.com.br

Evidências:

Checklist mínimo pós-deploy​

  1. Confirmar que o Deployment está apontando para a imagem repository:tag esperada.
  2. Confirmar que o secret *-envs existe e não ficou com PLACEHOLDER_*.
  3. Confirmar resposta HTTP do probe principal em /api/health.
  4. Confirmar entrada HTTPS do hostname do ambiente.

Evidências:

Rollback​

Fato observado

  • O pipeline de deploy usa helm upgrade --install com image.tag=${github.sha}.
  • O job de build publica a imagem também com a tag do commit SHA.
  • Não há job de rollback explícito nem uso comprovado de helm rollback no repositório.

Inferência controlada

  • O caminho de rollback mais aderente ao que está versionado aqui é reaplicar o mesmo comando de deploy apontando image.tag para um SHA anterior conhecido como saudável.

Evidências:

Procedimento sugerido a partir do mecanismo real de deploy​

  1. Identificar o último github.sha estável do ambiente.
  2. Reexecutar o helm dependency build helm.
  3. Reaplicar helm upgrade --install no namespace do ambiente, substituindo image.tag pelo SHA anterior.
  4. Validar /api/health após o rollout.

Exemplo:

helm dependency build helm
helm upgrade --install --create-namespace -n <namespace> <release-name> helm \
  -f kubernetes/<cluster>/<namespace>/values.yaml \
  --set image.repository=<registry>/<repository>/<app> \
  --set image.tag=<sha-anterior-saudavel>

Evidências:

Comandos úteis​

Aplicação​

npm run dev
npm run build
npm run start
npm run test:unit
npm run start:storybook
npm run build:storybook

Evidências:

Contêiner local​

docker-compose up --build -d

Evidências:

Pipeline/Helm​

docker build --build-arg NPM_TOKEN=<token> -t <image>:<tag> .
helm dependency build helm
helm upgrade --install --create-namespace -n <namespace> <release-name> helm \
  -f kubernetes/<cluster>/<namespace>/values.yaml \
  --set image.repository=<registry>/<repository>/<app> \
  --set image.tag=<tag>

Evidências:

Troubleshooting dos 5 incidentes mais prováveis​

1. Aplicação não sobe localmente​

Sintomas observáveis:

  • npm run dev ou npm run build falham por configuração ausente.
  • docker-compose falha por .env ausente ou rede dhedalos-network inexistente.

Ações:

  1. Conferir se o .env foi criado a partir de .env.example.
  2. Conferir se as variáveis de auth e integrações mínimas estão preenchidas.
  3. No fluxo em contêiner, confirmar a existência da rede externa dhedalos-network.

Evidências:

2. Deploy conclui, mas a aplicação fica unhealthy ou não responde​

Sintomas observáveis:

  • Probe principal falha.
  • O app responde status: "degraded" ou status: "unhealthy" em /api/health.

Ações:

  1. Verificar a imagem e a tag aplicadas no Deployment.
  2. Confirmar se o secret de ambiente não ficou com PLACEHOLDER_*.
  3. Verificar memory.usage, healthCheckDuration e consecutiveSlowChecks em /api/health.
  4. Se necessário, reaplicar o último SHA saudável.

Evidências:

3. Login falha, fica lento ou retorna mensagem de sobrecarga​

Sintomas observáveis:

  • Mensagens de erro ligadas à autenticação.
  • Timeout de 15s no fluxo de NextAuth.
  • Rejeição por excesso de requisições concorrentes.

Ações:

  1. Conferir NEXTAUTH_URL e NEXTAUTH_SECRET.
  2. Confirmar reachability e credenciais dos backends consultados na autenticação.
  3. Procurar por logs [Auth] Too many concurrent requests, [Auth] TIMEOUT after 15s e [Auth Error].

Evidências:

4. OTP ou envio de template falha​

Sintomas observáveis:

  • O envio do código falha em /v1/otp/send.
  • A confirmação falha em /v1/otp/confirm.
  • O envio do template após confirmação retorna erro.

Ações:

  1. Conferir API_WHATS_BASE_URL e API_WHATS_TOKEN.
  2. Procurar erros [API] ... whats/otpSend e [API] ... whats/sendFlowTemplate.
  3. Confirmar se a customização do curso retorna flow_template_id e flow_template_header_image.

Evidências:

5. Usuários caem em manutenção ou não conseguem entrar no curso/grupo​

Sintomas observáveis:

  • Redirecionamento global para /maintenance.
  • Página de curso retorna notFound.
  • Link de grupo não é resolvido.

Ações:

  1. Verificar a resposta do endpoint de maintenance mode do WordPress.
  2. Confirmar API_WP_BACKEND_URL e API_WP_BACKEND_TOKEN.
  3. Verificar se getCustomization, getCourseStatus e getGroupLink estão respondendo sem timeout.
  4. Procurar erros de middleware e de adapters wp/*.

Evidências:

Pendências​

  • O repositório não traz um procedimento automatizado de rollback.
  • O secret Helm usa PLACEHOLDER_*; a substituição real de valores não está documentada aqui.
  • O pipeline baixa .env do S3, mas o conteúdo desse arquivo não está versionado neste workspace.

Evidências: