Pular para o conteúdo principal

Runbook Operacional

Introdução ao documento​

Este runbook descreve os procedimentos operacionais para executar, implantar e recuperar o serviço activity-delivery-api.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-04
  • Responsável: Time Dhedalos

Referencial teórico​

Escopo​

  • Ambiente local (Docker Compose)
  • Deploy (GitHub Actions + Helm + Kubernetes)
  • Rollback
  • Troubleshooting

Fontes de verdade​

  • docker-compose.yml — serviços Docker locais
  • Dockerfile — build de produção
  • .github/workflows/ci-cd-pipeline.yaml — pipeline CI/CD
  • .github/workflows/test.yaml — pipeline de testes
  • helm/ — charts Helm para deploy Kubernetes
  • kubernetes/ — configs específicas por cluster

Como rodar local​

Pré-requisitos:

  • Docker e Docker Compose instalados
  • Node.js / npm instalados na máquina host
  • Portas disponíveis: 8000, 5173, 13306, 8025, 6379

Comandos:

# Start (primeira vez)
npm install
cp .env.example .env
docker-compose up --build
docker-compose exec laravel php artisan migrate --seed
docker-compose exec laravel php artisan key:generate
docker-compose exec laravel php artisan storage:link

# Start (subsequente)
docker-compose up

# Logs
docker-compose logs -f laravel

# Stop
docker-compose down

# Stop e limpar volumes
docker-compose down -v

Serviços Docker (local)​

ServiçoPortaDescrição
laravel8000Aplicação principal (PHP + Octane)
vite5173Build de frontend (assets)
mysql13306 (host) → 3306 (container)Banco de dados MySQL 8.0
mailhog8025Servidor de e-mail para testes
redis6379Cache e sessão

Deploy​

Pipeline CI/CD​

  • Trigger: push/PR em qualquer branch
  • Etapas:
    1. build — Build da imagem Docker, push para registry com tags (branch normalizada + SHA)
    2. deploy-piloto — Deploy automático na branch main para cluster oke-we-002, namespace piloto-dhedalos-ecosystem
    3. deploy-prod — Deploy automático na branch release para cluster oke-we-001, namespace dhedalos-ecosystem
  • Evidência: .github/workflows/ci-cd-pipeline.yaml:15-86

Pipeline de Testes​

  • Trigger: push/PR para branch main
  • Etapas:
    1. Setup PHP 8.2 + MySQL 8.0
    2. composer install (usa composer.ci.json para evitar dependências privadas)
    3. Migrations + seed
    4. PHP CS Fixer (se config presente)
    5. PHPStan (se config presente)
    6. php artisan test --coverage
    7. Upload de cobertura para Codecov
  • Bloqueio: deploy só acontece se testes passarem
  • Evidência: .github/workflows/test.yaml

Dockerfile (produção)​

  • Base: dunglas/frankenphp:1.3.2-php8.3.14
  • Extensões: pdo_mysql, pdo_pgsql, redis
  • Limites: memory 6144M, upload 5120M
  • Entrypoint: migrations → storage link → optimize → Octane FrankenPHP (porta 8000)
  • Worker: Supervisor configurado para artisan queue:work
  • Evidência: Dockerfile:1,30-33

Comando de deploy manual (Helm)​

# Piloto
helm upgrade --install activity-delivery-api ./helm \
  --namespace piloto-dhedalos-ecosystem \
  --kubeconfig <path-to-kubeconfig-oke-we-002>

# Produção
helm upgrade --install activity-delivery-api ./helm \
  --namespace dhedalos-ecosystem \
  --kubeconfig <path-to-kubeconfig-oke-we-001>

⚠️ PENDÊNCIA: Verificar valores reais do Helm chart (helm/values.yaml) para secrets, replicas e resource limits.

Rollback​

# Rollback Helm (última revisão)
helm rollback activity-delivery-api --namespace <namespace>

# Rollback para revisão específica
helm history activity-delivery-api --namespace <namespace>
helm rollback activity-delivery-api <revision> --namespace <namespace>

# Rollback de migration (local)
docker-compose exec laravel php artisan migrate:rollback

# Rollback de migration (N steps)
docker-compose exec laravel php artisan migrate:rollback --step=3

Comandos úteis​

Logs​

# Local — logs do container
docker-compose logs -f laravel

# Local — log viewer (browser)
# http://localhost:8000/admin/api-logs (requer login admin)

# Produção — kubectl
kubectl logs -f deployment/activity-delivery-api -n <namespace>

Migração / Schema​

# Executar migrations pendentes
docker-compose exec laravel php artisan migrate

# Status das migrations
docker-compose exec laravel php artisan migrate:status

# Rollback
docker-compose exec laravel php artisan migrate:rollback

# Fresh (drop all + migrate + seed) — APENAS DEV
docker-compose exec laravel php artisan migrate:fresh --seed

Cache / Otimização​

# Limpar cache de aplicação
docker-compose exec laravel php artisan cache:clear

# Limpar cache de configuração
docker-compose exec laravel php artisan config:clear

# Limpar cache de rotas
docker-compose exec laravel php artisan route:clear

# Otimizar para produção
docker-compose exec laravel php artisan optimize

Queue / Worker​

# Iniciar worker manualmente
docker-compose exec laravel php artisan queue:work

# Listar jobs falhados
docker-compose exec laravel php artisan queue:failed

# Reprocessar jobs falhados
docker-compose exec laravel php artisan queue:retry all

# Limpar jobs falhados
docker-compose exec laravel php artisan queue:flush

API Key​

# Gerar nova chave de API
docker-compose exec laravel php artisan api:key:generate --description="App Mobile"

Swagger​

# Regenerar documentação
docker-compose exec laravel php artisan l5-swagger:generate

Troubleshooting (Top 5)​

1. 401 Unauthorized na API​

  • Sintoma: Resposta 401 em chamadas à API.
  • Causa provável: API Key inválida ou ausente; JWT expirado (1h de validade).
  • Como diagnosticar: Verificar header Authorization na request; verificar se a API Key existe na tabela api_keys; verificar expiração do JWT.
  • Ação de correção: Gerar nova API Key (php artisan api:key:generate); obter novo JWT via GET /api/submissions/token.

2. Falha de upload de arquivo​

  • Sintoma: Erro 422 ou 500 ao submeter arquivos.
  • Causa provável: MIME type não permitido; tamanho excedendo limite; storage S3 inacessível.
  • Como diagnosticar: Verificar MIME types em app/Helpers/MimeTypes.php; verificar logs do Laravel; verificar configuração AWS no .env.
  • Ação de correção: Validar tipo de arquivo; ajustar upload_max_filesize / post_max_size no PHP; verificar credenciais AWS.

3. Notificação Novu não enviada​

  • Sintoma: Participante/facilitador não recebe notificação.
  • Causa provável: NOVU_SECRET_KEY inválida; app_key do workflow não encontrada na tabela novu_keys; Novu API fora do ar.
  • Como diagnosticar: Verificar logs do NotificationService; verificar tabela novu_keys; testar Novu API manualmente.
  • Ação de correção: Atualizar NOVU_SECRET_KEY no .env; inserir workflow correto na tabela novu_keys.

4. Falha de deploy (CI/CD)​

  • Sintoma: Pipeline falha no GitHub Actions.
  • Causa provável: Testes falhando; build Docker com erro; registry inacessível.
  • Como diagnosticar: Verificar logs do GitHub Actions; rodar testes localmente; verificar Dockerfile.
  • Ação de correção: Corrigir testes falhando; rebuild local da imagem Docker; verificar credenciais do registry.

5. Erro de conexão com banco de dados​

  • Sintoma: SQLSTATE[HY000] ou Connection refused.
  • Causa provável: Container MySQL não iniciou; credenciais incorretas no .env; banco não existe.
  • Como diagnosticar: docker-compose ps para verificar estado dos containers; verificar variáveis DB_* no .env.
  • Ação de correção: docker-compose restart mysql; verificar/corrigir credenciais; criar banco manualmente se necessário.

Pendências​

  • ⚠️ PENDÊNCIA: Documentar procedimento de rotação de secrets (JWT_SECRET, NOVU_SECRET_KEY, API Keys) em produção.
  • ⚠️ PENDÊNCIA: Documentar configuração de auto-scaling e resource limits Kubernetes a partir do Helm chart.
  • ⚠️ PENDÊNCIA: Documentar procedimento de backup e restore do banco de dados de produção.
  • ⚠️ PENDÊNCIA: Documentar liveness/readiness probes configuradas no Kubernetes.