Pular para o conteúdo principal

Runbook Operacional

Introducao ao documento​

Guia operacional para execucao local, deploy, rollback e troubleshooting da aplicacao schedule manager.

Versionamento​

  • Versao do documento: 1.0.0
  • Ultima atualizacao: 2026-03-17
  • Responsavel: GitHub Copilot

Referencial teorico​

  • Operacao de servicos containerizados
  • Boas praticas de CI/CD
  • Playbooks de incidentes

Execucao local​

Pre-requisitos​

  • Docker e Docker Compose.
  • Portas 8001 (app), 13306 (mysql) e 6379 (redis) disponiveis.
  • Evidencia: docker-compose.yml:10
  • Evidencia: docker-compose.yml:25
  • Evidencia: docker-compose.yml:46

Subida​

docker-compose up -d --build
cp .env.example .env
  • Evidencia: README.md:50
  • Evidencia: README.md:49

Bootstrap app​

docker exec -it laravel php artisan migrate --seed
docker exec -it laravel php artisan horizon
  • Evidencia: README.md:54
  • Evidencia: README.md:58

Verificacao minima​

curl -i http://localhost:8001/
curl -i http://localhost:8001/api/test-auth
  • Evidencia: docker-compose.yml:10
  • Evidencia: routes/api.php:50

Deploy​

Pipeline CI/CD em GitHub Actions executa build/push Docker e deploy Helm por branch.

Build e push​

  • job build em ubuntu-latest.
  • docker/build-push-action com tags branch-normalizada e sha.
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:14
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:40
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:47

Deploy ambientes​

  • develop -> deploy-piloto.
  • main -> deploy-essencia e deploy-prod.
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:53
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:84
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:115

Comando-base de deploy (workflow)​

helm dependency build helm
helm upgrade --install --create-namespace -n <namespace> <release> helm \
  -f kubernetes/<cluster>/<namespace>/values.yaml \
  --set image.repository=<registry/repository/image> \
  --set image.tag=<sha>
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:76
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:77
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:79

Rollback​

Rollback de release Helm​

helm -n <namespace> history <release>
helm -n <namespace> rollback <release> <revision>

Rollback por imagem​

Reexecutar helm upgrade apontando image.tag para sha anterior estavel.

  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:48
  • Evidencia: .github/workflows/ci-cd-pipeline.yaml:79

Comandos uteis​

Aplicacao​

php artisan migrate --force
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
  • Evidencia: docker/entrypoint.sh:5
  • Evidencia: docker/entrypoint.sh:6
  • Evidencia: docker/entrypoint.sh:7
  • Evidencia: docker/entrypoint.sh:10

Testes​

./vendor/bin/phpunit
  • Evidencia: phpunit.xml:2
  • Evidencia: phpunit.xml:7

Troubleshooting (5 incidentes provaveis)​

1) 401 Missing/Invalid Api Key em endpoints /api​

  • Sintoma: resposta 401 com message Missing Api Key ou Invalid Api Key.
  • Diagnostico: verificar header Authorization e existencia da key em api_keys.
  • Acao:
curl -i -H "Authorization: <api_key>" http://localhost:8001/api/appointments?week=10\&cpf=12345678909
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:24
  • Evidencia: app/Http/Middleware/ApiKeyMiddleware.php:41

2) Conflito ao criar agendamento​

  • Sintoma: HTTP 409 There is another appointment within the specified time range.
  • Diagnostico: confirmar janela start_time/finish_time e colaborador.
  • Acao: consultar agenda do colaborador na semana e slots do dia.
  • Evidencia: app/Http/Controllers/AppointmentController.php:174
  • Evidencia: app/Http/Controllers/AppointmentController.php:450

3) Falha no envio de e-mail​

  • Sintoma: notificacoes nao chegam.
  • Diagnostico: validar MAIL_* no env e worker de filas/horizon.
  • Acao:
php artisan horizon
php artisan queue:failed
  • Evidencia: app/Mail/AppointmentMail.php:9
  • Evidencia: config/mail.php:31
  • Evidencia: config/horizon.php:184

4) Exportacao CSV falha​

  • Sintoma: erro 500 em /api/export-appointments.
  • Diagnostico: checar credenciais AWS e permissao de escrita no bucket.
  • Acao: validar AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY/AWS_BUCKET e disco s3.
  • Evidencia: app/Http/Controllers/ExportAppointmentsController.php:92
  • Evidencia: config/filesystems.php:47
  • Evidencia: .env.example:39

5) Erro em migrate no startup de container​

  • Sintoma: container sobe, mas app nao responde corretamente.
  • Diagnostico: falha de conexao MySQL durante entrypoint.
  • Acao: validar servico mysql, credenciais e healthcheck.
  • Evidencia: docker/entrypoint.sh:10
  • Evidencia: docker-compose.yml:22
  • Evidencia: docker-compose.yml:33