Monitoring Modoboa with Vigilmon

Modoboa is a clean, modern open-source email hosting platform built on Python and Django. It provides a developer-friendly admin interface for managing email domains, mailboxes, aliases, and filtering rules — integrating with Postfix and Dovecot as the underlying MTA and IMAP server. When you self-host Modoboa, you own every layer of the email stack: the web admin, the mail transport, the IMAP server, and the background workers. Vigilmon monitors all of them, so you hear about failures before your users do.

What You'll Set Up

• HTTP uptime monitor for the Modoboa web admin UI
• Modoboa REST API health check with token authentication
• TCP port monitors for Postfix SMTP (25) and Dovecot IMAP SSL (993)
• SSL certificate expiry alerts for HTTPS admin and mail TLS
• Heartbeat monitoring for Modoboa's Celery background task workers

Prerequisites

• Modoboa installed on Linux with Postfix and Dovecot
• Modoboa admin UI accessible over HTTP/HTTPS
• A Modoboa API token (generated in the admin panel under API access)
• A free Vigilmon account

Step 1: Monitor the Modoboa Web Admin UI

The Modoboa admin interface is your control plane for all email domains and mailboxes. A down web UI means you cannot respond to account requests or configuration changes.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Modoboa URL: https://mail.yourdomain.com (or the HTTP URL if you haven't set up SSL yet).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

The Modoboa login page loads the Django application — a 200 response here confirms nginx (or Apache), uWSGI/Gunicorn, and the Modoboa Django app are all responding.

Step 2: Monitor the Modoboa REST API

Modoboa ships a REST API that exposes domain and mailbox data. Monitoring the /api/v1/domains/ endpoint confirms the API is up, authentication is working, and the database is responding — a richer signal than the login page alone.

1. Click Add Monitor in Vigilmon.
2. Set Type to HTTP / HTTPS.
3. Enter: https://mail.yourdomain.com/api/v1/domains/
4. Under Request headers, add:

   Authorization: Token YOUR_MODOBOA_API_TOKEN
   

5. Set Expected HTTP status to 200.
6. Under Response body, set Contains to "name" to confirm the JSON domain list is returned.
7. Set Check interval to 3 minutes.
8. Click Save.

If the API returns 401, your token has expired or been revoked — this is a real configuration problem, not a transient failure. If it returns 500, the Django app or database layer has a fault.

Step 3: TCP Port Monitors for Postfix and Dovecot

Modoboa manages mail administration, but the actual email flow runs through Postfix and Dovecot. These processes run independently of the web admin and must be monitored separately.

Postfix SMTP Port 25 (Inbound Mail)

1. Click Add Monitor → set Type to TCP Port.
2. Enter your mail server hostname: mail.yourdomain.com
3. Set Port to 25.
4. Set Check interval to 1 minute.
5. Click Save.

Dovecot IMAP SSL Port 993 (Mail Retrieval)

1. Click Add Monitor → set Type to TCP Port.
2. Enter mail.yourdomain.com.
3. Set Port to 993.
4. Set Check interval to 1 minute.
5. Click Save.

Port 25 down means no new email reaches your server. Port 993 down means users cannot fetch their email from mail clients. These are separate failure modes — monitor both.

Step 4: SSL Certificate Alerts

Self-hosted Modoboa deployments often use Let's Encrypt for HTTPS and Postfix/Dovecot TLS. Certificate expiry silently breaks both the admin UI and mail client connections.

Web Admin HTTPS Certificate

1. Open the HTTP monitor you created in Step 1.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

SMTP STARTTLS Certificate (Postfix)

1. Open the TCP Port 25 monitor you created in Step 3.
2. Enable Monitor SSL certificate — Vigilmon probes STARTTLS on SMTP ports.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

IMAP SSL Certificate (Dovecot)

1. Open the TCP Port 993 monitor.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

A Postfix or Dovecot certificate expiry is more damaging than a web admin expiry — mail clients and other mail servers will reject connections immediately with no graceful degradation.

Step 5: Heartbeat Monitoring for Celery Workers

Modoboa uses Celery for background tasks including statistics collection, quota enforcement, and cleanup jobs. If the Celery worker process dies, these tasks silently stop running — quotas are not enforced, statistics go stale, and administrative jobs are skipped.

Modoboa's /api/v1/information/ endpoint returns server information including version and configuration details. Use it as a lightweight background-health check, combined with a periodic Celery queue depth probe:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set Expected ping interval to 10 minutes.
3. Copy the heartbeat ping URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. On your Modoboa server, add a cron job that checks the information endpoint and confirms Celery is processing:

# /etc/cron.d/modoboa-celery-heartbeat
*/10 * * * * modoboa bash -c '
  # Check API is responding
  API_OK=$(curl -sf -H "Authorization: Token YOUR_API_TOKEN" \
    https://localhost/api/v1/information/ -o /dev/null && echo ok)
  
  # Check Celery worker is alive
  CELERY_OK=$(cd /srv/modoboa && source env/bin/activate && \
    celery -A modoboa inspect ping -d celery@$(hostname) --timeout 5 2>/dev/null | grep -c pong)
  
  # Ping heartbeat only if both are healthy
  [ "$API_OK" = "ok" ] && [ "$CELERY_OK" -gt 0 ] && \
    curl -s https://vigilmon.online/heartbeat/abc123
'

If the Celery worker crashes, the inspect ping returns no pong responses, the heartbeat ping is skipped, and Vigilmon alerts you after 10 minutes of silence.

For a simpler check if you prefer, just verify the Celery worker PID file exists and the process is running:

*/10 * * * * modoboa pgrep -f "celery.*modoboa" > /dev/null && \
  curl -sf -H "Authorization: Token YOUR_API_TOKEN" \
    https://localhost/api/v1/information/ > /dev/null && \
  curl -s https://vigilmon.online/heartbeat/abc123

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add your notification channels (email, Slack, webhook).
2. For Postfix and Dovecot TCP monitors, set Consecutive failures before alert to 2 — brief connection timeouts happen during legitimate maintenance.
3. For the Modoboa API monitor, set Consecutive failures before alert to 1 — a 500 or 403 from the API is always significant.
4. Set up a Maintenance window in Vigilmon before running Modoboa upgrades (pip install modoboa --upgrade + python manage.py migrate), as the Django app briefly stops during migration:

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_VIGILMON_API_KEY" \
  -d '{"monitor_id": "YOUR_MODOBOA_MONITOR_ID", "duration_minutes": 5}'

Summary

| Monitor | Type | Target | What It Catches | |---|---|---|---| | Web admin UI | HTTP | https://mail.yourdomain.com | Django/nginx crash | | REST API | HTTP | /api/v1/domains/ | Database or API fault | | Postfix SMTP | TCP Port | Port 25 | Inbound mail failure | | Dovecot IMAP SSL | TCP Port | Port 993 | Mail retrieval failure | | Web admin SSL | SSL Certificate | mail.yourdomain.com | HTTPS cert expiry | | SMTP STARTTLS SSL | SSL Certificate | Port 25 STARTTLS | Postfix TLS cert expiry | | IMAP SSL | SSL Certificate | Port 993 | Dovecot TLS cert expiry | | Celery heartbeat | Cron Heartbeat | Celery ping + API check | Background worker crash |

Modoboa gives you a modern, developer-friendly email admin platform with full data ownership. With Vigilmon covering the web UI, REST API, mail ports, SSL certificates, and Celery worker health, you have complete observability across every layer of your self-hosted email stack.