Runbook: Setup de Alerting en Dokploy (STAGE y PROD)

Objetivo

Activar alerting de PROD (y STAGE) en Dokploy: montar la API key de Resend, confirmar dominios, y testear que los emails llegan.

Estado: Draft — esperando primer deploy real.

Prerrequisitos

• Acceso SSH a los servidores de Dokploy (STAGE y PROD).
• API key de Resend SMTP (solicitar al equipo de infra).
• Confirmación de que el dominio crearack.com está verificado en Resend (verificado en s94).
• Confirmación de que logcrearack@esfericlabs.com existe y está activo.

Procedimiento

Paso 1: Crear el fichero de secret en STAGE

# SSH al host de STAGE
ssh user@stage.dokploy.server

# Navegar a la ruta de Dokploy (example: /home/dokploy/projects/crearack)
cd /home/dokploy/projects/crearack

# Crear el directorio files/ si no existe
mkdir -p files

# Crear el fichero smtp_password con la clave de Resend
# (una línea única, sin quotes, sin trailing newline)
echo -n "re_XXXXXXXXXXXXXXXXXXXXX" > files/smtp_password

# Verificar permisos (solo el usuario dokploy puede leer)
chmod 600 files/smtp_password

# Verificar contenido (sin extras)
cat files/smtp_password | od -c  # no debe haber \n al final

Resultado esperado: archivo con 1 línea, 28-32 caracteres, no visible en git status (gitignored).

Paso 2: Crear el fichero de secret en PROD

Repetir el Paso 1 en el servidor PROD (misma estructura).

ssh user@prod.dokploy.server
cd /home/dokploy/projects/crearack
mkdir -p files
echo -n "re_YYYYYYYYYYYYYYYYYYYYYYY" > files/smtp_password
chmod 600 files/smtp_password

Paso 3: Verificar configuración de Resend

En el dashboard de Resend (https://resend.com/emails):

1. Sender domain: verificar que crearack.com está en estado “Verified”.
2. API keys: crear o reutilizar una key SMTP (no regular API).
3. Email to: confirmar que logcrearack@esfericlabs.com es un buzón válido.

Nota: el remitente noreply@crearack.com debe ser un subdominio válido del dominio verificado.

Paso 4: Deploy en STAGE

En Dokploy (UI o CLI), hacer pull del código (PR#49 ya mergeado):

# En el contenedor/VM de Dokploy STAGE
cd code/
git pull origin main

# Verificar que compose.prod.yml existe y referencia ../files/smtp_password
grep "files/smtp_password" compose.prod.yml

# Levantar los servicios nuevos (o redeploy completo)
docker-compose -f compose.prod.yml up -d vmalert alertmanager

# Verificar logs
docker logs crearack_alertmanager -f
docker logs crearack_vmalert -f

Logs esperados:

• alertmanager: “Listening on :9093”.
• vmalert: “Reading rules from /etc/alerts/alerts.yml” + “5 rules loaded”.
• Ningún error SMTP aún — es normal, esperando primera alerta.

Paso 5: Smoke test en STAGE

5a. Forzar una alerta CreaRackDown

# Detener el servicio web para simular caída
docker stop crearack_web

# Esperar 30s (intervalo de evaluación de vmalert)
sleep 30

# Verificar que vmalert dispara
docker logs crearack_vmalert | grep "CreaRackDown" | tail -5

# Verificar que Alertmanager la recibe
curl http://localhost:9093/api/v2/alerts | jq '.[] | select(.labels.alertname=="CreaRackDown")'

# Salida esperada: alerta en estado `firing`

5b. Verificar intento de envío de email

# En los logs de Alertmanager debe haber un intento SMTP
docker logs crearack_alertmanager | grep -i smtp | tail -10

# Log esperado: "sending email to logcrearack@esfericlabs.com"
# o "authentication successful" o similar (depende de versión)

# Si la clave es válida, debe decir "250 Email queued" (OK)
# Si la clave es inválida, debe decir "535 Authentication credentials invalid"

5c. Confirmar en Resend dashboard

Login en Resend, revisar “Activity” o “Logs” — debe haber un intento de envío (fallido o exitoso).

5d. Reiniciar el web

docker start crearack_web

# Esperar 30s, vmalert debe cambiar la alerta a `resolved`
# Alertmanager envía notificación de resolución

docker logs crearack_alertmanager | grep -i resolved

Paso 6: Confirmar que el email llegó

• Revisar buzón de logcrearack@esfericlabs.com.
• Email debe:
  • De: CreaRack Pro <noreply@crearack.com>.
  • Asunto: [CreaRack PROD] ACTIVE · CreaRackDown (u otro estado).
  • Body: plantilla de Alertmanager con detalles de la alerta.

Si no llega: revisar Paso 3 (dominio verificado) y Paso 2 (clave válida).

Paso 7: Deploy en PROD

Una vez STAGE está verde (Paso 5-6):

# Crear secret en PROD (Paso 2)
# Luego en Dokploy PROD:
cd code/
git pull origin main
docker-compose -f compose.prod.yml up -d vmalert alertmanager
docker logs crearack_alertmanager -f

Paso 8: Monitoreo inicial

• Primeras 24h: revisar buzón de logcrearack@ cada 4h (para validar que no hay alertas falsas).
• Umbrales: si hay spam de alertas, ajustar --evaluationInterval en vmalert o umbrales en alerts.yml.
• Histórico: en http://localhost:9093 (STAGE only) revisar alertas históricas.

Rollback

Si alerting genera ruido excesivo o causa problemas:

# Detener vmalert y alertmanager (desactiva alerting, vuelve solo UptimeRobot)
docker stop crearack_vmalert crearack_alertmanager

# O comentar en compose.prod.yml y redeploy
# (pero esto requiere revert de PR#49 — mejor solo detener servicios)

Troubleshooting

Información de contacto

• Resend support: https://resend.com/support.
• Dokploy dashboard: URL del servidor.
• Alerts: logcrearack@esfericlabs.com.

Véase también

• [[feature—observability—alerting-prod-s95]]
• [[decision—20260529—plan-hardening-post-master-hito-a]]
• [[entity—observability—service—alertmanager]]
• [[entity—observability—service—vmalert]]
• [[runbook—observability—alerting-setup]]