Notificar por e-mail quando o backup do PostgreSQL falhar

[edvaldoszy]

Contexto

O serviço script/database-backup/ já roda diariamente via cron, gera o dump .sql.gz e envia para o Google Drive. Em caso de erro (falha no pg_dump, upload via rclone, retenção, etc.), o script aborta (set -euo pipefail), mas o erro só aparece nos logs do CapRover — ninguém é avisado automaticamente.

A API do herbário já usa SMTP (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM) para envio de e-mails. O serviço de backup pode seguir o mesmo modelo de variáveis.

---

Objetivo

Adicionar notificação por e-mail apenas em caso de falha do backup, de forma que o time seja avisado sem depender de monitoramento manual dos logs.

---

Comportamento esperado

1. O cron continua executando o backup no horário configurado
2. Se o backup terminar com sucesso → não enviar e-mail
3. Se qualquer etapa falhar → enviar e-mail com:
   • Assunto claro (ex.: falha no backup de {DATABASE_NAME})
   • Horário da tentativa (TZ)
   • Mensagem de erro / saída relevante do script (quando disponível)
4. O alerta deve aceitar múltiplos destinatários (lista configurável)
5. Falha no envio do e-mail não deve esconder a falha original do backup (o job deve continuar falhando)

---

Escopo técnico (alto nível)

• Introduzir um passo de notificação no fluxo do cron (ex.: executar o backup e, em caso de falha, chamar um script/função de notify)
• Cliente SMTP: msmtp no container do backup (não reutilizar nodemailer da API — o serviço é Debian + bash, sem Node)
• Instalar msmtp no Dockerfile do database-backup
• Configurar o msmtp a partir das variáveis SMTP_* (no entrypoint ou equivalente)
• Interpretar NOTIFY_EMAIL_TO como lista de e-mails (ex.: separados por vírgula)
• Documentar as novas variáveis em .env.example / README do serviço
• Reaproveitar o padrão de nomes das env vars SMTP já usado no projeto

---

Variáveis de ambiente (proposta)

Variável	Descrição	Exemplo
SMTP_HOST	Servidor SMTP	smtp.gmail.com
SMTP_PORT	Porta SMTP	587
SMTP_USER	Usuário SMTP	seu-email@gmail.com
SMTP_PASS	Senha / app password	(segredo)
SMTP_FROM	Remetente	Sistema HCF <no-reply@hcf.com>
NOTIFY_EMAIL_TO	Destinatários do alerta (1 ou mais, separados por vírgula)	ops@exemplo.com,curadoria@exemplo.com

Opcional (se fizer sentido no PR):

• NOTIFY_EMAIL_ENABLED=true|false — para desligar temporariamente sem remover config

---

Critérios de aceite

• Em falha do backup, um e-mail é enviado via msmtp para todos os destinatários em NOTIFY_EMAIL_TO
• NOTIFY_EMAIL_TO aceita um único e-mail ou vários separados por vírgula
• Em sucesso do backup, nenhum e-mail é enviado
• O e-mail identifica banco, horário e motivo/erro da falha
• msmtp instalado e configurado no container do database-backup
• Variáveis SMTP/notify documentadas em .env.example (e README, se existir)
• O fluxo funciona no mesmo padrão CapRover/cron do database-backup
• Falha ao enviar e-mail não mascara a falha do backup nos logs/exit code

---

Checklist de testes

• Forçar falha (ex.: senha inválida / host inacessível) e confirmar recebimento do e-mail
• Testar com dois ou mais destinatários e confirmar que todos recebem
• Rodar backup com sucesso e confirmar que não chega e-mail
• Validar logs no CapRover: falha do dump/upload + tentativa de notificação via msmtp
• Testar com SMTP real usado pelo ambiente (mesmas credenciais da API, se aplicável)

---

Fora do escopo

• Notificação em caso de sucesso
• Heartbeat / detecção de “backup não rodou” (cron parado)
• Outros canais (Telegram, Discord, Slack, WhatsApp)
• Alteração da política de retenção ou do formato do dump

---

Referências

• Serviço existente: script/database-backup/
• SMTP já usado na API: variáveis SMTP_* em .env.example