Monitoring ERPNext with Vigilmon

ERPNext is a full-featured open-source ERP system covering manufacturing, accounting, HR, CRM, inventory, and supply chain — all built on the Frappe Python framework. Thousands of SMEs worldwide run it self-hosted, which means they also own its uptime. ERPNext's architecture involves the Frappe web server, Redis (caching and queuing), MariaDB, and background workers for email and scheduled jobs. When any of these components fails, business operations halt. Vigilmon monitors the full stack: the login page, the Frappe health API, Redis connectivity, SSL certificates, and the background workers that keep scheduled processes running.

What You'll Set Up

• HTTP monitor for the ERPNext web UI (login page)
• HTTP monitor for the /api/method/frappe.utils.doctor health check endpoint
• TCP port monitor for Redis (port 6379)
• SSL certificate expiry alerts for HTTPS ERPNext setups
• Cron heartbeat for ERPNext background workers (Frappe scheduler)

Prerequisites

• ERPNext 15.x (or Frappe v15 bench) installed and running
• Redis accessible on the ERPNext host
• A free Vigilmon account

Step 1: Monitor the ERPNext Login Page

The ERPNext login page confirms the Frappe WSGI application, gunicorn workers, and nginx proxy are all operational.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your ERPNext URL: https://erp.yourdomain.com/.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword check, enter ERPNext (or Frappe) to confirm the app renders correctly.
7. Click Save.

The keyword check is important: if the Frappe app crashes and gunicorn restarts, nginx may serve a 502 or redirect to an error page while the app is recovering. A keyword check catches the brief recovery window that a pure status-code check might miss.

Step 2: Monitor the Frappe Health Check Endpoint

Frappe exposes a built-in doctor utility via the API at /api/method/frappe.utils.doctor. This endpoint returns the health status of the Frappe application including database connectivity, Redis, and scheduler state.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: https://erp.yourdomain.com/api/method/frappe.utils.doctor.
3. Set Check interval to 5 minutes.
4. Set Expected HTTP status to 200.
5. Under Keyword check, enter "message" to confirm a valid JSON response.
6. Click Save.

To verify the endpoint manually:

curl -s https://erp.yourdomain.com/api/method/frappe.utils.doctor | python3 -m json.tool

A healthy response looks like:

{
  "message": {
    "message": "Production mode"
  }
}

If you want a more targeted check, add a keyword for "Production mode" to confirm ERPNext is running in the expected mode rather than debug mode.

Step 3: Monitor the Redis Port

Frappe uses Redis for session caching, background job queuing (via RQ), and real-time event publishing. ERPNext typically connects to Redis on port 6379. If Redis goes down, background jobs stop, sessions may fail to persist, and real-time features (notifications, desk updates) break.

1. Click Add Monitor → TCP Port.
2. Enter the Redis host (localhost or the dedicated Redis server hostname).
3. Set Port to 6379.
4. Set Check interval to 1 minute.
5. Click Save.

If your ERPNext bench uses multiple Redis instances (Frappe bench may use ports 11000, 12000, 13000 for cache, queue, and socketio), add a TCP monitor for each port:

# Check which Redis ports are in use by your bench
cat /home/frappe/frappe-bench/config/redis_cache.conf | grep port
cat /home/frappe/frappe-bench/config/redis_queue.conf | grep port

Add a separate TCP monitor for each active Redis port.

Step 4: SSL Certificate Alerts for HTTPS ERPNext Setups

ERPNext installations managed by Frappe's bench tool can auto-configure nginx with Let's Encrypt via bench setup lets-encrypt. Certificate expiry means accountants, warehouse managers, and HR staff all lose access simultaneously.

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

For multi-site Frappe bench setups where multiple ERPNext sites share the same server but have separate domains, add an SSL monitor for each site's domain:

# List all sites in your bench
ls /home/frappe/frappe-bench/sites/

# Check certificate for each site
echo | openssl s_client -connect site1.yourdomain.com:443 2>/dev/null | openssl x509 -noout -enddate

Step 5: Heartbeat Monitoring for ERPNext Background Workers

The Frappe scheduler drives ERPNext's most critical automated processes: email sending, payment reminders, report generation, data sync, and inventory updates. The scheduler runs as a separate process (bench start or systemd unit frappe-schedule). If it stops, these jobs fall silent with no visible error in the ERPNext desk UI.

Set up a Vigilmon heartbeat to detect a stopped scheduler:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 15 minutes.
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Add a cron job that checks the scheduler process and pings Vigilmon:

# /etc/cron.d/erpnext-heartbeat
*/15 * * * * frappe /usr/bin/systemctl is-active --quiet frappe-schedule.service && curl -s https://vigilmon.online/heartbeat/abc123

For bench-managed setups using Supervisor:

*/15 * * * * frappe /usr/bin/supervisorctl status frappe-bench-frappe-schedule | grep -q RUNNING && curl -s https://vigilmon.online/heartbeat/abc123

You can also ping from within a Frappe scheduled job. Add a custom scheduled task in your app's hooks.py:

scheduler_events = {
    "hourly": [
        "your_app.tasks.ping_vigilmon_heartbeat"
    ]
}

# your_app/tasks.py
import requests

def ping_vigilmon_heartbeat():
    requests.get("https://vigilmon.online/heartbeat/abc123", timeout=5)

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and connect email, Slack, or a webhook to your infrastructure team.
2. Set Consecutive failures before alert to 2 on the web UI monitor — gunicorn restarts during bench updates take a few seconds.
3. Set Consecutive failures before alert to 1 on the Redis TCP monitor — a dead queue means background jobs are already failing.
4. Add a separate alert channel routed to the business team for the web UI monitor (ERP downtime affects operations, not just IT).

For ERPNext upgrades:

# Pause monitoring before bench update
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "erpnext-webui", "duration_minutes": 20}'

cd /home/frappe/frappe-bench
bench update --pull --patch --build

# Maintenance window expires automatically

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP — web UI | https://erp.yourdomain.com/ | Gunicorn crash, nginx misconfiguration | | HTTP — health check | /api/method/frappe.utils.doctor | Frappe app internal failure | | TCP port | Redis :6379 | Queue/cache down, background jobs halted | | SSL certificate | ERPNext domain | Certificate expiry, Let's Encrypt failure | | Cron heartbeat | Heartbeat URL | Scheduler crash, missed scheduled jobs |

ERPNext runs some of the most business-critical processes in an SME — payroll, invoicing, purchase orders, inventory. Vigilmon ensures that the moment any component of the Frappe stack goes silent, your team knows before employees or customers experience the impact.