vps/runbooks/mailcow-update.md

Runbook: mailcow update (mx2)

Target: mx2.windy.me
Path: /opt/mail
Confirm with the user before running an update.

Before

1. Run mailcow-health (or ./scripts/check-mx2.sh). Record baseline.
2. Note config quirks in mailcow.conf, especially:
   • SKIP_CLAMD=y — after update, clamd may still be running until services are recreated per mailcow docs.
   • SKIP_LETS_ENCRYPT, ports, hostname — should stay mx2.windy.me.
3. Disk/memory: df -h / and free -h on the host.

Update

ssh -t windy@mx2.windy.me 'cd /opt/mail && ./update.sh'

• Prefer interactive SSH (-t) so prompts work.
• Do not pass secrets into the chat log; do not commit mailcow.conf.

If update asks to stop/recreate containers, allow it unless the user said otherwise.

After

1. Re-run health checks (mailcow-health).

2. Confirm UI: https://mx2.windy.me

3. Confirm SMTP banner and queue empty.

4. If SKIP_CLAMD=y but cow-clamd-mailcow-1 is still Up and that is unwanted:

   cd ansible
   ansible-playbook playbooks/compose-reconcile.yml --limit mailcow \
     -e '{"service_reconcile_confirm": true, "service_reconcile_targets": ["all"]}'
   

   Only after user OK; recreate briefly interrupts mail.

5. Update Verified on hosts/mx2.windy.me.md with date and outcome.

Rollback

Mailcow updates are image/git based; there is no one-click rollback in this runbook. If something fails, capture docker compose ps and docker compose logs --tail=100 for the failing service and stop before further changes.