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.

Versionamento​

  • Versão do documento: 1.0.0
  • Última atualização: 2026-03-09
  • Responsável: Marivaldo Vinicius

Referencial teórico​

Escopo​

  • Ambiente local (desenvolvimento)
  • Deploy em produção (Kubernetes/Helm)
  • Rollback
  • Troubleshooting

Fontes de verdade​

  • Configuração Docker: docker-compose.yml e Dockerfiles
  • Scripts de inicialização: entrypoint.sh
  • Configuração de produção: Helm charts e Dockerfile

Como rodar local​

Pré-requisitos​

  • Docker e Docker Compose instalados
  • PHP >= 8.2 (apenas se rodar sem Docker)
  • Composer >= 2.7.2 (apenas se rodar sem Docker)
  • Node >= 18 (apenas se rodar sem Docker)
  • MySQL >= 8.0.32 (apenas se rodar sem Docker)

Ambiente Docker Compose​

O projeto utiliza Docker Compose com três serviços principais:

  1. laravel: Aplicação PHP/Laravel (porta 8000)
  2. vite: Servidor de desenvolvimento frontend (porta 5173)
  3. mysql: Banco de dados MySQL 8.0 (porta 13306)

Comandos:

# Iniciar todos os serviços
docker compose up

# Iniciar em background
docker compose up -d

# Parar serviços
docker compose down

# Reconstruir containers
docker compose up --build

# Ver logs
docker compose logs -f laravel
docker compose logs -f vite
docker compose logs -f mysql

Variáveis de ambiente​

O ambiente local utiliza variáveis do arquivo .env. Principais variáveis:

  • APP_PORT: Porta da aplicação (padrão: 8000)
  • VITE_PORT: Porta do Vite (padrão: 5173)
  • SAIL_XDEBUG_MODE: Modo Xdebug (padrão: off)
  • SAIL_XDEBUG_CONFIG: Configuração Xdebug

Configuração inicial:

# Copiar arquivo de exemplo
cp .env.example .env

# Gerar chave da aplicação
docker compose exec laravel php artisan key:generate

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

Inicialização automática​

O entrypoint do container Laravel (docker/dev/entrypoint.sh) executa automaticamente:

  1. Configura autenticação Composer para Backpack
  2. Instala dependências via Composer
  3. Cria link simbólico de storage
  4. Otimiza aplicação
  5. Executa migrações
  6. Gera chave da aplicação
  7. Publica assets do Log Viewer
  8. Inicia Supervisor para workers

Primeira execução​

# 1. Iniciar containers
docker compose up -d

# 2. Aguardar inicialização completa (verificar logs)
docker compose logs -f laravel

# 3. Executar migrações e seeders
docker compose exec laravel php artisan migrate --seed

# 4. Criar usuário admin
docker compose exec laravel php artisan backpack:user

# 5. Acessar aplicação
# http://localhost:8000 (aplicação)
# http://localhost:5173 (Vite dev server)

Deploy​

Pipeline atual​

O deploy em produção utiliza Kubernetes com Helm charts. Configuração em helm/values.yaml e templates em helm/templates/.

Processo de deploy:

  1. Build da imagem Docker (baseada em Dockerfile)
  2. Push para registry (registry.nuvem.online/weconcept/dhedalos-app-dashboard-laravel)
  3. Deploy via Helm no cluster Kubernetes
  4. Execução do entrypoint (entrypoint.sh) que:
    • Cria link de storage
    • Otimiza aplicação
    • Executa migrações
    • Publica assets do Log Viewer
    • Inicia Supervisor

Imagem de produção​

A imagem de produção (Dockerfile) utiliza:

  • Base: dunglas/frankenphp:1.3.2-php8.3.14
  • Servidor: Laravel Octane com FrankenPHP
  • Workers: Supervisor gerencia 4 processos de queue worker
  • Build: Frontend compilado via npm run build

Configuração Kubernetes​

  • Replicas: Configurável via helm/values.yaml (padrão: 1)
  • Service: ClusterIP
  • Ingress: Configurável (desabilitado por padrão)
  • Autoscaling: Configurável (desabilitado por padrão)

Rollback​

Rollback via Helm​

# Listar releases
helm list

# Ver histórico de releases
helm history <release-name>

# Rollback para versão anterior
helm rollback <release-name>

# Rollback para versão específica
helm rollback <release-name> <revision-number>

Rollback manual​

  1. Identificar versão anterior da imagem
  2. Atualizar helm/values.yaml com tag da imagem anterior
  3. Aplicar via helm upgrade

Comandos úteis​

Logs​

# Logs da aplicação (local)
docker compose logs -f laravel

# Logs do worker (local)
docker compose exec laravel tail -f storage/logs/laravel-supervisor-worker.log

# Logs em produção (Kubernetes)
kubectl logs -f <pod-name>
kubectl logs -f <pod-name> -c laravel-worker

Migração e schema​

# Executar migrações
docker compose exec laravel php artisan migrate

# Executar migrações com seeders
docker compose exec laravel php artisan migrate --seed

# Reverter última migração
docker compose exec laravel php artisan migrate:rollback

# Ver status das migrações
docker compose exec laravel php artisan migrate:status

Cache​

# Limpar todos os caches
docker compose exec laravel php artisan cache:clear
docker compose exec laravel php artisan config:clear
docker compose exec laravel php artisan route:clear
docker compose exec laravel php artisan view:clear

# Otimizar aplicação
docker compose exec laravel php artisan optimize

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

Queue e workers​

# Processar jobs manualmente
docker compose exec laravel php artisan queue:work

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

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

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

Nota: Em produção, workers são gerenciados pelo Supervisor (4 processos configurados em laravel-worker.conf).

Frontend​

# Desenvolvimento (hot reload)
docker compose exec vite npm run dev

# Build de produção
docker compose exec vite npm run build

# Build Storybook
docker compose exec vite npm run build-storybook

Swagger/API Docs​

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

# Acessar documentação
# http://localhost:8080/api/documentation#/default

Testes​

Testes Backend (Pest PHP)​

# Executar todos os testes
docker compose exec laravel php artisan test

# Executar com Pest diretamente
docker compose exec laravel ./vendor/bin/pest

# Executar apenas testes unitários
docker compose exec laravel ./vendor/bin/pest tests/Unit

# Executar apenas testes de feature
docker compose exec laravel ./vendor/bin/pest tests/Feature

# Executar com cobertura
docker compose exec laravel ./vendor/bin/pest --coverage --min=100

# Executar teste específico
docker compose exec laravel php artisan test --filter="NomeDoTeste"

Testes E2E (Cypress)​

Pré-requisitos:

  • Aplicação Laravel rodando em http://localhost:8000
  • Dependências Node instaladas (npm install)
  • Usuário de teste criado no banco de dados

Comandos:

# Abrir Cypress Test Runner (interface gráfica)
npm run cypress:open

# Executar testes em modo headless
npm run cypress:run

Criar usuário de teste:

# Via Tinker
docker compose exec laravel php artisan tinker
# Criar usuário com email e senha conhecidos

# Ou via seeder (se configurado)
docker compose exec laravel php artisan db:seed --class=CypressUserSeeder

Variáveis de ambiente para Cypress:

# Configurar URL base (opcional, default: http://localhost:8000)
export CYPRESS_BASE_URL=http://localhost:8000

# Configurar credenciais de teste (opcional)
export CYPRESS_USER_EMAIL=test@example.com
export CYPRESS_USER_PASSWORD=password

Troubleshooting de testes Cypress:

# Verificar se aplicação está rodando
curl http://localhost:8000/up

# Verificar logs do servidor
docker compose logs laravel

# Limpar cache antes de executar testes
docker compose exec laravel php artisan cache:clear
docker compose exec laravel php artisan config:clear

# Verificar se usuário de teste existe
docker compose exec laravel php artisan tinker
# App\Models\User::where('email', 'test@example.com')->first();

Documentação completa: docs/tests/cypress.md

Troubleshooting (Top 5)​

1. Erro 500 - Aplicação não inicia​

Sintoma: Aplicação retorna erro 500 ou não responde.

Causas prováveis:

  • Cache de configuração desatualizado
  • Variáveis de ambiente não configuradas
  • Permissões de storage incorretas
  • Banco de dados não acessível

Diagnóstico:

# Verificar logs
docker compose logs laravel

# Verificar variáveis de ambiente
docker compose exec laravel php artisan config:show

# Verificar conexão com banco
docker compose exec laravel php artisan tinker
# DB::connection()->getPdo();

Correção:

# Limpar caches
docker compose exec laravel php artisan config:clear
docker compose exec laravel php artisan cache:clear

# Verificar permissões
docker compose exec laravel chmod -R 775 storage bootstrap/cache

# Verificar .env
docker compose exec laravel cat .env | grep DB_

2. Jobs não processam / Fila travada​

Sintoma: Jobs ficam na fila e não são processados.

Causas prováveis:

  • Worker não está rodando
  • Conexão com queue driver falhou
  • Timeout de jobs muito baixo
  • Memória insuficiente

Diagnóstico:

# Verificar workers (local)
docker compose exec laravel supervisorctl status

# Verificar jobs na fila
docker compose exec laravel php artisan queue:work --once

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

Correção:

# Reiniciar workers (local)
docker compose exec laravel supervisorctl restart laravel-worker:*

# Processar jobs manualmente
docker compose exec laravel php artisan queue:work --tries=3

# Verificar configuração de queue
docker compose exec laravel php artisan config:show queue

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

Sintoma: Erro "SQLSTATE[HY000] [2002] Connection refused" ou similar.

Causas prováveis:

  • MySQL não está rodando
  • Credenciais incorretas no .env
  • Porta incorreta
  • Rede Docker não configurada

Diagnóstico:

# Verificar se MySQL está rodando
docker compose ps mysql

# Testar conexão
docker compose exec laravel php artisan tinker
# DB::connection()->getPdo();

# Verificar variáveis de ambiente
docker compose exec laravel env | grep DB_

Correção:

# Reiniciar MySQL
docker compose restart mysql

# Verificar logs do MySQL
docker compose logs mysql

# Verificar .env
# DB_HOST deve ser 'mysql' (nome do serviço no docker-compose)
# DB_PORT deve ser 3306 (porta interna do container)

4. Cache não atualiza / Dados desatualizados​

Sintoma: Dados retornados pela API estão desatualizados mesmo após atualização.

Causas prováveis:

  • Cache não foi limpo após atualização
  • Jobs de cache não executaram
  • TTL do cache muito longo
  • Cache driver não configurado corretamente

Diagnóstico:

# Verificar status do cache
docker compose exec laravel php artisan cache:table

# Verificar jobs de cache
docker compose exec laravel php artisan queue:failed

# Verificar configuração de cache
docker compose exec laravel php artisan config:show cache

Correção:

# Limpar cache manualmente
docker compose exec laravel php artisan cache:clear

# Disparar atualização de cache via API (requer autenticação)
# GET /api/v1/cache/inscricoes

# Ou via artisan
docker compose exec laravel php artisan tinker
# Cache::flush();

5. Erro de permissão / Storage não acessível​

Sintoma: Erro ao salvar arquivos, uploads falham, ou logs não são escritos.

Causas prováveis:

  • Permissões incorretas em storage/ e bootstrap/cache/
  • Link simbólico de storage não criado
  • Usuário do container sem permissões

Diagnóstico:

# Verificar permissões
docker compose exec laravel ls -la storage/
docker compose exec laravel ls -la public/

# Verificar link simbólico
docker compose exec laravel ls -la public/storage

Correção:

# Corrigir permissões
docker compose exec laravel chmod -R 775 storage bootstrap/cache
docker compose exec laravel chown -R www-data:www-data storage bootstrap/cache

# Recriar link de storage
docker compose exec laravel php artisan storage:link --force

Comandos de manutenção​

Backup​

# Backup do banco de dados (local)
docker compose exec mysql mysqldump -u laravel -p laravel > backup.sql

# Restore
docker compose exec -T mysql mysql -u laravel -p laravel < backup.sql

Limpeza​

# Limpar containers parados
docker compose down

# Limpar volumes (CUIDADO: apaga dados)
docker compose down -v

# Limpar imagens não utilizadas
docker system prune -a

Monitoramento de recursos​

# Uso de recursos dos containers
docker stats

# Espaço em disco
docker system df