fit-boilerplate-wox/docs/RUNBOOK.md

RUNBOOK — Operaciones

Cómo monitorear, recuperar, rotar y troubleshootear una solución desplegada con este template.

URLs y endpoints clave

URL	Para qué
https://$PUBLIC_HOST/	Landing con chat embed
https://$PUBLIC_HOST/web/	App principal (UI)
https://$PUBLIC_HOST/health	Healthcheck (200 = todo OK)
https://$PUBLIC_HOST/api/traces	Vista timeline de tool calls (admin)
WxO Console	Settings, agents, channels
Coolify panel	Deploy, logs, env vars

Monitoring

Healthcheck simple

curl -sf "https://$PUBLIC_HOST/health" && echo OK || echo FAIL

Smoke test nightly

Configurar CI/cron que corra cada noche:

./evals/smoke-test.sh

Si falla, alerta por email/Slack.

Logs en tiempo real

# Local
docker compose logs -f --tail=100

# Coolify
# Panel → app → Logs tab

Buscar:

• ERROR o Exception en stdout
• recursion_limit (issue I-001)
• kid not found (issue I-004)
• 422 Unprocessable Entity (issue I-003)

Recovery procedures

El chat embed quedó en "Cargando..."

1. Settings → Embed Security debe estar Off. Issue I-007.
2. Verificar que el agentId y agentEnvironmentId del HTML coincidan con orchestrate agents list --env live.
3. Browser console: buscar errores CORS o 401.

Casos atascados en executing (issue I-012)

El watchdog del backend los promueve a paused automáticamente después de 90s. Si no pasa:

1. Ver logs: grep "case_id=XXXX"
2. Si Orchestrate jamás llamó al callback, el run murió: re-trigger desde la UI
3. Si el callback llegó pero la DB no actualizó, ver issue I-013

El agente printea tool calls como texto (issue I-002)

1. Verificar llm: en el YAML del agente = groq/openai/gpt-oss-120b
2. Verificar que REGLA #0 está en el prompt
3. Si persiste con gpt-oss-120b → reportar a IBM, es regresión del modelo

Pydantic 422 en tool calls (issue I-003)

1. Ver el payload exacto que el LLM mandó (logs del backend)
2. Si stringificó algo que debería ser int/list → falta @field_validator(mode="before")
3. Agregar el validator, redeployar el backend

Deploy WxO falla con kid not found (issue I-004)

# Re-configurar la connection en live
orchestrate connections configure -a <app_id> --env live --type team --kind <kind>
orchestrate connections set-credentials -a <app_id> --env live -e "BASE_URL=..."

# Re-deployar agente
orchestrate agents deploy --name <agent> --env live

Coolify dio 503 después de redeploy (issue I-008)

1. docker logs <container> → buscar healthcheck failures
2. Cambiar wget --spider a wget -qO- en el Dockerfile
3. Rebuild

Backend OK pero WxO no llega (issue I-008/I-009)

# Probar desde fuera
curl -sf "https://$PUBLIC_HOST/api/v1/health"

# Si 200 OK pero WxO da timeout → firewall/network
# Si 503 → Traefik/healthcheck
# Si TRAEFIK DEFAULT CERT → labels manuales, ver I-009

Rotación de secretos

API key del tenant WxO

1. WxO Console → IAM → Generate new API key
2. Actualizar .env: ORCHESTRATE_API_KEY=<nuevo>
3. docker compose up -d --force-recreate (NO restart, issue I-011)
4. orchestrate env activate <env-name> con el nuevo key

Credenciales de connection

orchestrate connections set-credentials -a <app_id> --env draft -e "BASE_URL=..." -e "API_KEY=<nuevo>"
orchestrate connections set-credentials -a <app_id> --env live  -e "BASE_URL=..." -e "API_KEY=<nuevo>"

No hay que re-deployar agentes — las connections se resuelven en runtime.

Webhook signing secret

1. Generar nuevo secret
2. Actualizar .env + Coolify env vars: WEBHOOK_SECRET=<nuevo>
3. --force-recreate
4. Si el sistema externo usa el viejo secret, coordinar el switch

Backup y restore

Backup

• Código + YAMLs: vive en Gitea. Backup automático del repo.
• Backend DB: docker exec <db-container> pg_dump > backup.sql (o equivalente)
• Audit logs: parte del backup de la DB
• Trazas SQLite: cp web/data/traces.db backup/
• WxO config: los YAMLs del repo. orchestrate agents list te dice qué está en live.

Restore

• Código: git clone y ./scripts/deploy-wxo.sh
• DB: pg_restore < backup.sql
• Traces: si las perdés, no es crítico (son observabilidad histórica)

Disaster recovery completo

1. Clonar repo en nuevo host
2. .env con credenciales del tenant (las que ya tenías guardadas)
3. ./scripts/deploy-wxo.sh — recrea todo en WxO desde los YAMLs
4. docker compose up -d — levanta backend/web
5. Restore DB si necesario
6. Capturar nuevos IDs, propagar
7. Smoke test

Tiempo objetivo: <30 min.

Troubleshooting checklist

Cuando algo se rompe y no sabés por dónde empezar:

1. curl -sf $PUBLIC_HOST/health — ¿el servicio responde?
2. docker ps — ¿los containers están healthy?
3. docker logs <container> --tail=200 — ¿hay errores recientes?
4. orchestrate agents list — ¿el agente está en live?
5. ./evals/direct-backend-probe.sh — ¿la auth funciona?
6. ./evals/smoke-test.sh — ¿el flujo end-to-end?
7. WxO Console → Runs → últimos runs — ¿qué error tienen?
8. docs/known-issues.md — ¿coincide con algún I-XXX?

Si después de los 8 sigue roto, escalalo. Pero el 90% de los problemas están en uno de los 8.

Versión / actualización del ADK

./scripts/check-adk-version.sh

Si hay nueva versión:

1. NO actualizar directamente.
2. Crear branch chore/adk-X.Y.Z
3. pip install ibm-watsonx-orchestrate==X.Y.Z
4. Re-deployar a un env de staging
5. Correr todas las evals
6. Si pasan, PR + merge + deploy a prod
7. Actualizar el pin en requirements.txt + check-adk-version.sh

Cuando todo lo demás falla

Ver docs/known-issues.md y docs/adk-2x-cheatsheet.md. Si tampoco está ahí, abrir issue en el repo del template para que la próxima persona no lo sufra.