Skip to content

RUNBOOK.md

Latest commit

 

History

History
119 lines (83 loc) · 5.33 KB

RUNBOOK.md

File metadata and controls

119 lines (83 loc) · 5.33 KB
Raw

RUNBOOK — whatsapp-bot en AWS Lightsail

Operaciones rutinarias post-migración. Para detalles del diseño ver LIGHTSAIL_MIGRATION_PLAN.md.

Estado actual del setup (al momento del handoff)

  • Instancia: AWS Lightsail, plan $10/mo (1 GB RAM, 2 vCPU burst, 40 GB SSD), región us-east-1.
  • IP estática: attachada a la instancia. No tocar / no detachar — el webhook de Meta apunta a este FQDN.
  • Dominio del webhook: <ip-estatica>.nip.io (servicio gratuito de DNS dinámico). No hay dominio propio registrado. Esta decisión fue consciente al cierre del proyecto — funciona en producción sin problemas
  • TLS: Caddy emite y renueva certs Let's Encrypt automáticamente. Cero gestión manual.
  • Snapshots automáticos: deshabilitados. Si se quiere habilitarlos (~$2/mo), Lightsail Console → instancia → tab "Snapshots" → Enable automatic snapshots.

Acceso

  • SSH: ssh ubuntu@<ip-estatica> con la key generada desde la instancia (Lightsail Console → Account → SSH keys).
  • Working dir: /opt/whatsapp-bot.
  • Logs app: docker compose -f /opt/whatsapp-bot/docker-compose.yml logs -f app.
  • Logs Caddy: docker compose -f /opt/whatsapp-bot/docker-compose.yml logs -f caddy.
  • Logs cron: tail -f /var/log/whatsapp-bot-cron.log.

Deploy de cambios

cd /opt/whatsapp-bot
git pull
docker compose up -d --build

El healthcheck del compose espera 15s antes de la primera evaluación; si docker compose ps muestra app en healthy en <30s, OK.

⚠️ git pull NO trae cambios de .env. El .env está gitignoreado, así que cualquier env var nueva que introduzca un commit (ej. LLM_MODEL) hay que agregarla a mano en /opt/whatsapp-bot/.env antes del docker compose up -d --build. Si la var no se agrega, el código usa su default (no rompe), pero el cambio de configuración no surte efecto. Después de editar .env, docker compose up -d --build recrea el container con el env nuevo. Verificá con docker compose ps (healthy) y docker compose logs --tail 50 app (sin errores de arranque).

Restart de un service

docker compose restart app   # solo el bot
docker compose restart caddy # solo el reverse proxy
docker compose up -d         # recrea cualquier service con env vars nuevas

Rotar un secret en .env

  1. Editar /opt/whatsapp-bot/.env (chmod 600). Cambiar el valor.
  2. Si rotás NOTIFICATIONS_INTERNAL_SECRET, también actualizar /opt/whatsapp-bot/.cron-secret (chmod 600 owner ubuntu).
  3. docker compose up -d para recrear el container app con el nuevo env.

Aplicar una migración de Supabase

cd /opt/whatsapp-bot
psql "$DATABASE_URL" -v ON_ERROR_STOP=1 -f supabase/migrations/<archivo>.sql

El bot no requiere restart — las migraciones impactan solo a Supabase.

Disparar el cron manualmente

curl -fsS -X POST http://localhost:8000/internal/notifications/run \
  -H "X-Internal-Secret: $(cat /opt/whatsapp-bot/.cron-secret)"

Para dry-run (no envía, solo cuenta):

curl -fsS -X POST 'http://localhost:8000/internal/notifications/run?dry_run=true' \
  -H "X-Internal-Secret: $(cat /opt/whatsapp-bot/.cron-secret)"

Cambiar el dominio del webhook

  1. Editar DOMAIN=... en /opt/whatsapp-bot/.env.
  2. docker compose up -d caddy → Caddy emite cert nuevo automáticamente (Let's Encrypt HTTP-01).
  3. Actualizar el Callback URL en Meta Business Manager → WhatsApp → Configuration.

Si el dominio nuevo no resuelve a la IP estática de la instancia, Caddy no puede pasar el challenge y el cert no emite. Revisar docker compose logs caddy por errores obtain certificate.

Aprobación de pagos (manual, hasta que exista un dashboard)

En Supabase:

  1. Table Editor
  2. Pagos Reportados
  3. Actualizar el valor de la columna "status_verificacion" en la fila del pago correspondiente a "aprobado".
UPDATE pagos_reportados
SET status_verificacion = 'aprobado'
WHERE id = '<uuid del pago>';

El trigger fn_apply_pago_on_approval reparte el monto FIFO sobre las cuotas vencidas; el sobrante va a creditos_cliente. Una fila pago_aprobado queda en notificaciones y el siguiente cron drainea el WhatsApp al cliente.

Aplicación manual de creditos_cliente

Decisión de producto: los créditos NO auto-aplican. Cuando el cliente acepta usar su crédito a favor:

-- inspeccionar primero
SELECT * FROM creditos_cliente WHERE cliente_id = '<uuid>' AND applied_at IS NULL;

-- aplicar (con la lógica de negocio que corresponda — esto es el patrón mínimo)
UPDATE creditos_cliente SET applied_at = NOW() WHERE id = '<uuid_credito>';
-- + UPDATE cuotas.monto_pagado_acumulado en la cuota destino
  • Tambien se puede hacer en el dashboard de Supabase

Monitoreo

Si "el bot no responde", primero:

  1. curl https://<dominio>/health desde tu máquina.
  2. SSH y docker compose ps. Si app está unhealthy → docker compose logs --tail 100 app.
  3. Si la VM no responde a SSH → Lightsail Console → instancia → "Reboot".

No tocar

  • caddy_data volume → certs persistidos. Si lo borrás, Caddy re-emite (cuidado con rate limits de Let's Encrypt).
  • WA_META_APP_SECRET → si rota, las firmas HMAC de mensajes en vuelo fallan hasta que Meta refresque. Coordinar.
  • WA_PHONE_NUMBER_ID / WA_BUSINESS_ACCOUNT_ID → identidad de la cuenta de WhatsApp Business; no se cambian en operación normal.