Runbook Operacional

0) Escopo

Operacao do backend WordPress do Dhedalos em:

• ambiente local com Docker Compose;
• ambientes Kubernetes provisionados por Helm, via pipeline GitHub Actions.

Este runbook cobre:

• execucao local;
• deploy;
• rollback;
• comandos de operacao;
• troubleshooting dos 5 incidentes mais provaveis.

0.1 Fontes de verdade

• docker-compose.yml
• Dockerfile
• wp/wp-su.sh
• .github/workflows/ci-cd-pipeline.yml
• helm/Chart.yaml
• helm/templates/_helpers.tpl
• helm/templates/deployment.yaml
• helm/templates/wp-cron-deployment.yaml
• helm/values.yaml
• kubernetes/oke-we-001/dhedalos-ecosystem/values.yaml
• kubernetes/oke-we-001/essencia-ecosystem/values.yaml
• kubernetes/oke-we-002/piloto-dhedalos-ecosystem/values.yaml
• we-dhedalos/functions/wp/rest_path.php
• we-dhedalos/functions/rest/auth_callback.php
• we-dhedalos/functions.php
• we-dhedalos/functions/utils/cache.php
• we-dhedalos/functions/utils/notify_course_start_date_cron.php
• we-dhedalos/functions/utils/auto_cancel_enrollments_cron.php
• we-dhedalos/functions/utils/inactive_users_notification_cron.php
• we-dhedalos/functions/utils/last_day_notification_cron.php

1) Como rodar local

1.1 Pre-requisitos

• Docker + Docker Compose disponiveis.
• Porta 80 livre (Nginx local) e 3306 livre (MariaDB local).

Evidencias:

• docker-compose.yml:5
• docker-compose.yml:49

1.2 Subida

docker compose up -d --build

Servicos esperados:

• mariadb
• redis
• wordpress (PHP-FPM)
• nginx
• init (one-shot para copia de plugins)

Evidencias:

• docker-compose.yml:2
• docker-compose.yml:56

1.3 Verificacao basica

docker compose ps
docker compose logs -f nginx wordpress mariadb redis

1.4 Smoke de aplicacao

curl -I http://localhost
curl --request GET --url 'http://localhost/api/dhedalos/v1/theme_settings'
curl --request GET \
  --url 'http://localhost/api/dhedalos/v1/live/cycles' \
  --header 'Authorization: Svc <API_SERVICE_TOKEN>'

Evidencias:

• Prefixo REST /api: we-dhedalos/functions/wp/rest_path.php:5
• Callback token de servico: we-dhedalos/functions/rest/auth_callback.php:2

2) Como deployar (pipeline atual)

2.1 Fluxo da pipeline

Workflow: .github/workflows/ci-cd-pipeline.yml

Passos implementados:

1. checkout;
2. normalizacao de tag de branch;
3. login no Docker Registry;
4. build e push da imagem;
5. deploy Helm por branch alvo.

Evidencias:

• .github/workflows/ci-cd-pipeline.yml:18
• .github/workflows/ci-cd-pipeline.yml:21
• .github/workflows/ci-cd-pipeline.yml:33
• .github/workflows/ci-cd-pipeline.yml:40

2.2 Mapeamento de ambientes

Branch	Cluster	Namespace	Release Helm	Values file
develop	oke-we-002	piloto-dhedalos-ecosystem	dhedalos-app-backend-wp	kubernetes/oke-we-002/piloto-dhedalos-ecosystem/values.yaml
main	oke-we-001	dhedalos-ecosystem	dhedalos-app-backend-wp	kubernetes/oke-we-001/dhedalos-ecosystem/values.yaml
main	oke-we-001	essencia-ecosystem	essencia-app-backend-wp	kubernetes/oke-we-001/essencia-ecosystem/values.yaml
development	oke-we-002	dev-dhedalos-wp	dhedalos-app-backend-wp-dev	kubernetes/oke-we-002/dev-dhedalos-wp/values.yaml

Evidencias:

• .github/workflows/ci-cd-pipeline.yml:51
• .github/workflows/ci-cd-pipeline.yml:83
• .github/workflows/ci-cd-pipeline.yml:115
• .github/workflows/ci-cd-pipeline.yml:147

2.3 Comando-base de deploy (igual ao 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/name> \
  --set image.tag=<github.sha>

Evidencias:

• .github/workflows/ci-cd-pipeline.yml:77
• .github/workflows/ci-cd-pipeline.yml:78

2.4 Pre-checks antes de deploy manual

helm lint helm
helm dependency build helm
kubectl -n <namespace> get deploy,po,svc,ing

Observacao:

• nome final do deployment pode variar por fullnameOverride ou combinacao release + chart.

Evidencias:

• Regra de naming: helm/templates/_helpers.tpl:13
• Override em Essencia: kubernetes/oke-we-001/essencia-ecosystem/values.yaml:1

2.5 Pos-checks apos deploy

kubectl -n <namespace> get deploy,pods
kubectl -n <namespace> rollout status deploy/<deployment-name>
kubectl -n <namespace> get ingress

Valide endpoint publico do ambiente:

• Piloto: https://admin.piloto.sebraeingresse.com.br/api/dhedalos/v1/theme_settings
• Producao: https://admin.sebraeingresse.com.br/api/dhedalos/v1/theme_settings
• Essencia: https://admin.essencia.dhedalos.com/api/dhedalos/v1/theme_settings

Evidencias:

• kubernetes/oke-we-002/piloto-dhedalos-ecosystem/values.yaml:8
• kubernetes/oke-we-001/dhedalos-ecosystem/values.yaml:9
• kubernetes/oke-we-001/essencia-ecosystem/values.yaml:11

3) Como rollback

3.1 Rollback Helm para revisao anterior

helm -n <namespace> history <release>
helm -n <namespace> rollback <release> <revision>
helm -n <namespace> status <release>
kubectl -n <namespace> rollout status deploy/<deployment-name>

3.2 Rollback por imagem (sha anterior)

Como o workflow publica image.tag=<github.sha>, tambem e possivel reexecutar deploy apontando para um SHA anterior conhecido:

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

Evidencias:

• tag por SHA no workflow: .github/workflows/ci-cd-pipeline.yml:48
• deploy com --set image.tag: .github/workflows/ci-cd-pipeline.yml:80

4) Comandos uteis

4.1 Logs

Local:

docker compose logs -f nginx wordpress mariadb redis

Kubernetes:

kubectl -n <namespace> get deploy
kubectl -n <namespace> logs deploy/<deployment-name> -c dhedalos-app-backend-wp-phpfpm --tail=200 -f
kubectl -n <namespace> logs deploy/<deployment-name> -c dhedalos-app-backend-wp-nginx --tail=200 -f

Evidencias:

• nomes de containers: helm/templates/deployment.yaml:49, helm/templates/deployment.yaml:85

4.2 Migrations

Nao foi encontrado framework de migrations dedicado (Laravel/Django/Doctrine) no repositorio.

Comandos relevantes de manutencao de schema WP:

docker compose exec wordpress wp core update-db
docker compose exec wordpress wp db query "SHOW TABLES LIKE '<prefix>user_patch_log';"
docker compose exec wordpress wp db query "SHOW TABLES LIKE '<prefix>simplybook_api_requests_log';"
docker compose exec wordpress wp db query "SHOW TABLES LIKE '<prefix>user_logs';"

Nota:

• substitua <prefix> pelo prefixo real (WORDPRESS_TABLE_PREFIX), que por padrao local e wp_.

Observacoes de criacao automatica de tabelas customizadas:

• user_patch_log: hook after_switch_theme
• user_logs: hook after_setup_theme
• simplybook_api_requests_log: criado quando SimpleBookLogTable e instanciada

Evidencias:

• we-dhedalos/functions/utils/create_patch_log_table.php:8
• we-dhedalos/functions/utils/log_user.php:24
• we-dhedalos/functions/3rd/log.php:22

4.3 Cache clear

docker compose exec wordpress wp cache flush
docker compose exec wordpress wp transient delete --all

Comportamento automatico no codigo:

• flush global em pre_post_update.

Evidencias:

• we-dhedalos/functions/utils/cache.php:28
• we-dhedalos/functions/utils/cache.php:33

4.4 Assincrono (cron worker / queue restart equivalente)

Nao existe fila baseada em broker (RabbitMQ/SQS/Kafka) neste repositorio. O processamento assincrono e feito por WP-Cron, com:

• execucao manual/local via WP-CLI;
• deployment dedicado wp-cron no Kubernetes (loop a cada 10 minutos).

Operacao local:

docker compose exec wordpress wp cron event list
docker compose exec wordpress wp cron event run --due-now

Operacao Kubernetes:

kubectl -n <namespace> get deploy
kubectl -n <namespace> logs deploy/<release>-wp-cron -c wp-cron --tail=200 -f
kubectl -n <namespace> exec deploy/<release>-wp-cron -c wp-cron -- \
  wp cron event run --due-now --allow-root --path=/var/www/html

Executar hooks especificos (quando necessario, local):

docker compose exec wordpress wp cron event run course_start_today_notify
docker compose exec wordpress wp cron event run auto_cancel_enrollments_daily
docker compose exec wordpress wp cron event run inactive_users_notification_daily
docker compose exec wordpress wp cron event run last_day_notification_daily

Evidencias:

• we-dhedalos/functions/utils/notify_course_start_date_cron.php:19
• we-dhedalos/functions/utils/auto_cancel_enrollments_cron.php:31
• we-dhedalos/functions/utils/inactive_users_notification_cron.php:31
• we-dhedalos/functions/utils/last_day_notification_cron.php:31
• helm/templates/wp-cron-deployment.yaml:4
• helm/templates/wp-cron-deployment.yaml:54
• helm/templates/wp-cron-deployment.yaml:89
• helm/templates/wp-cron-deployment.yaml:91

4.5 Comandos WP-CLI no container

A imagem instala wrapper wp para executar como www-data:

docker compose exec wordpress wp --info

Evidencias:

• Dockerfile:16
• wp/wp-su.sh:4

5) Troubleshooting (top 5)

5.1 401 auth em rotas de servico

Sintoma:

• endpoints com rest_auth_validate_token negam acesso.

Diagnostico:

1. Verifique valor de API_SERVICE_TOKEN no runtime.
2. Verifique header Authorization: Svc <token>.
3. Confirme se a rota realmente exige token.

Checks:

curl --request GET \
  --url 'http://localhost/api/dhedalos/v1/live/cycles' \
  --header 'Authorization: Svc <API_SERVICE_TOKEN>'

Evidencias:

• we-dhedalos/functions/rest/auth_callback.php:3
• docker-compose.yml:40

5.2 Timeout em integracoes externas

Sintoma:

• lentidao/erro em agenda, notificacao ou limpeza de arquivos externos.

Diagnostico:

1. Ver logs do wordpress.
2. Validar variaveis de integracao (Novu, API de submissions).
3. Validar disponibilidade dos endpoints externos.

Checks:

docker compose logs --tail=200 wordpress

Evidencias de timeout no codigo:

• submissions: we-dhedalos/functions.php:104
• simplybook cURL: we-dhedalos/functions/3rd/simplybook.php:127

5.3 Cron nao rodando

Sintoma:

• notificacoes/cancelamentos diarios nao executam.

Diagnostico:

1. Listar eventos cron.
2. Rodar eventos vencidos manualmente.
3. Em Kubernetes, confirmar se o deployment wp-cron esta em execucao e sem restart anormal.
4. Testar gatilhos admin por query string.

Checks:

docker compose exec wordpress wp cron event list
docker compose exec wordpress wp cron event run --due-now
kubectl -n <namespace> get deploy,pods | grep wp-cron
kubectl -n <namespace> logs deploy/<release>-wp-cron -c wp-cron --tail=200

Gatilhos admin implementados:

• ?executar_limpeza_atividades_submetidas=1
• ?execute_auto_cancel_enrollments=1
• ?execute_inactive_users_notification=1
• ?execute_last_day_notification=1

Evidencias:

• we-dhedalos/functions.php:54
• we-dhedalos/functions/utils/auto_cancel_enrollments_cron.php:23
• we-dhedalos/functions/utils/inactive_users_notification_cron.php:23
• we-dhedalos/functions/utils/last_day_notification_cron.php:23
• helm/templates/wp-cron-deployment.yaml:4
• helm/templates/wp-cron-deployment.yaml:87

5.4 Processamento assincrono parado

Sintoma:

• backlog de processamento assincrono.

Diagnostico no contexto deste repo:

• nao existe fila baseada em broker;
• backlog normalmente equivale a eventos WP-Cron pendentes ou falha no deployment wp-cron.

Acao:

1. Aplicar diagnostico de cron (item 5.3).
2. Verificar logs do container wp-cron.
3. Verificar se hooks de cron esperados existem na lista de eventos.

Evidencias:

• we-dhedalos/functions.php:45
• we-dhedalos/functions/utils/notify_course_start_date_cron.php:8
• helm/templates/wp-cron-deployment.yaml:54

5.5 CORS

Sintoma:

• browser bloqueia chamadas cross-origin para /api/*.

Diagnostico:

1. Confirmar origem chamadora e host de API.
2. Verificar configuracao de Ingress (anotacoes e controlador).
3. Verificar Nginx versionado (nao ha bloco explicito de CORS no repo).

Checks:

kubectl -n <namespace> get ingress -o yaml

Evidencias:

• docker/nginx.conf:1
• kubernetes/oke-we-001/dhedalos-ecosystem/values.yaml:3
• kubernetes/oke-we-002/piloto-dhedalos-ecosystem/values.yaml:2

6) Pendencias

• O caminho kubernetes/oke-we-002/dev-dhedalos-wp/values.yaml e referenciado no workflow, mas nao foi encontrado no estado atual do repositorio.
  • Evidencia: .github/workflows/ci-cd-pipeline.yml:174
• Nao existe job dedicado de rollback na pipeline atual.
  • Evidencia: .github/workflows/ci-cd-pipeline.yml:50
• Nao foi identificado sistema de fila com broker neste repositorio (somente WP-Cron).
  • Evidencia: we-dhedalos/functions.php:45