Monitoring NodeBB with Vigilmon

NodeBB is a modern open-source forum platform built on Node.js, offering real-time WebSocket communication, a rich plugin ecosystem, and Redis or MongoDB as its backing store. It powers gaming communities, developer hubs, and enterprise intranets as a capable successor to phpBB and vBulletin. But self-hosting means you own the uptime — and NodeBB's real-time features add monitoring surfaces beyond a simple HTTP ping. Vigilmon covers all of them: web UI availability, REST API health, Socket.IO connectivity, SSL certificates, and cron heartbeats for scheduled tasks.

What You'll Set Up

• HTTP uptime monitor for the NodeBB web UI
• REST API availability check on /api/config
• Socket.IO HTTP upgrade check on /socket.io/
• SSL certificate expiry alerts for HTTPS deployments
• Cron heartbeat for NodeBB scheduled tasks (digest emails, sitemap, notification queue)

Prerequisites

• NodeBB installed and accessible over HTTP or HTTPS
• A free Vigilmon account

Step 1: Monitor the NodeBB Web UI

The homepage is your primary availability signal — if it goes down, no one can access the forum.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your NodeBB URL: https://forum.yourdomain.com.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

NodeBB serves its SPA shell on the root path. A 200 response confirms nginx (or Caddy) is proxying correctly and the NodeBB process is alive.

Step 2: Monitor the NodeBB REST API (/api/config)

NodeBB exposes a REST API used by its own frontend. The /api/config endpoint returns a JSON configuration object and is a reliable signal that the application layer is healthy — not just the reverse proxy.

1. Add a new monitor and set Type to HTTP / HTTPS.
2. Enter: https://forum.yourdomain.com/api/config
3. Set Expected HTTP status to 200.
4. Enable Keyword check and enter "relative_path" (a field always present in the config response).
5. Set Check interval to 2 minutes.
6. Click Save.

A keyword match confirms the API returned valid JSON, ruling out cases where nginx returns a cached error page with a 200 status code.

Step 3: Monitor Socket.IO WebSocket Connectivity

NodeBB's real-time features (live post updates, notifications, online user counts) depend on Socket.IO. The Socket.IO handshake begins as an HTTP request to /socket.io/ before upgrading to a WebSocket connection. Monitoring the HTTP upgrade path confirms the WebSocket layer is reachable.

1. Add a new monitor with Type HTTP / HTTPS.
2. Enter: https://forum.yourdomain.com/socket.io/?EIO=4&transport=polling
3. Set Expected HTTP status to 200.
4. Set Check interval to 2 minutes.
5. Click Save.

The transport=polling parameter triggers Socket.IO's long-polling fallback, which responds with a valid JSON handshake payload over plain HTTP — no WebSocket upgrade required from the monitoring probe. If this endpoint returns a non-200 or times out, real-time features are broken even if the forum homepage loads.

Step 4: SSL Certificate Alerts

NodeBB forums are public-facing and almost always run on HTTPS. A lapsed certificate locks out your entire user base.

1. Open the HTTP monitor for https://forum.yourdomain.com (created in Step 1).
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

If NodeBB runs on a custom domain with a separate certificate from your main site, add a dedicated SSL monitor for that domain. A 21-day lead time gives you ample runway to renew before users see browser warnings.

Step 5: Heartbeat Monitoring for NodeBB Scheduled Tasks

NodeBB's built-in scheduler handles digest emails, sitemap generation, and the notification queue. These tasks run silently — a failure produces no HTTP error; it just means emails stop sending and sitemaps go stale. Use Vigilmon's cron heartbeat to verify each critical scheduled task completes on time.

Create a Heartbeat Monitor

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Give it a name like NodeBB digest email job.
3. Set the expected ping interval to match your job frequency (e.g., 1440 minutes for a daily digest).
4. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/abc123).

Send the Ping from a NodeBB Plugin

The cleanest integration is a small NodeBB plugin that hooks into the scheduler. Add this to your plugin's library.js:

const fetch = require('node-fetch');

// Called after the digest email job completes
async function onDigestComplete() {
  try {
    await fetch('https://vigilmon.online/heartbeat/abc123');
  } catch (e) {
    // Non-fatal — log but don't block the job
    console.error('[vigilmon] heartbeat ping failed:', e.message);
  }
}

Hook it into the NodeBB scheduler event your job fires on completion, or wrap your existing job function to call onDigestComplete() at the end.

Alternative: System-Level Cron

If you trigger NodeBB tasks from a system cron job instead, append the curl call:

# /etc/cron.daily/nodebb-sitemap
cd /path/to/nodebb && node app.js --generate-sitemap
curl -s https://vigilmon.online/heartbeat/abc123

If the job crashes or hangs and never pings, Vigilmon alerts after the expected interval passes.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook.
2. Set Consecutive failures before alert to 2 on the web UI monitor — NodeBB restarts or process manager recovery (PM2, systemd) take a few seconds and may cause a single probe to fail transiently.
3. Use Maintenance windows to suppress alerts during NodeBB upgrades or plugin installs:

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

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://forum.yourdomain.com | NodeBB process down, proxy failure | | REST API | /api/config | Application layer failure, bad config | | Socket.IO | /socket.io/?EIO=4&transport=polling | Real-time features broken | | SSL certificate | Forum domain | Certificate expiry, renewal failure | | Cron heartbeat | Heartbeat URL | Digest emails stopped, sitemap stale |

NodeBB's real-time architecture means a partial failure — the homepage loads but WebSockets are broken — is invisible without explicit endpoint checks. With Vigilmon watching all four surfaces, you get early warning on every failure mode before your community notices.