tutorial

Monitoring CodiMD with Vigilmon

CodiMD (HackMD Community Edition) is a self-hosted real-time collaborative markdown editor — but WebSocket-based collaboration is fragile. Here's how to monitor every critical service with Vigilmon.

CodiMD (the community edition of HackMD) is a self-hosted real-time collaborative markdown editor built on Node.js. It's the kind of tool teams reach for during incident postmortems, documentation sprints, and live meeting notes — exactly when a service interruption is most disruptive. CodiMD's reliance on WebSockets, a PostgreSQL database, and OAuth providers means there are multiple independent failure points beyond the basic web server. Vigilmon gives you coverage across every layer so you catch problems before they interrupt a collaboration session.

What You'll Set Up

  • HTTP uptime monitor for the CodiMD web server (port 3000)
  • WebSocket real-time collaboration health check
  • Note persistence API monitor
  • Image upload endpoint monitoring
  • Database connectivity health probe
  • Session management endpoint monitoring
  • OAuth provider connectivity check

Prerequisites

  • CodiMD running and accessible (typically on port 3000 or behind a reverse proxy)
  • A free Vigilmon account

Step 1: Monitor the CodiMD Web Server

The web server is CodiMD's front door. A basic HTTP check confirms the Node.js process is alive and serving the application.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your CodiMD URL: https://codimd.yourdomain.com (or http://your-server:3000).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

CodiMD returns a 302 redirect to /login for unauthenticated requests on the root path. If you see a 302, either monitor the login page directly or configure Vigilmon to accept 302 as a valid response.

Step 2: Add a Health Endpoint to CodiMD

CodiMD exposes a /status endpoint by default that returns application health information:

GET https://codimd.yourdomain.com/status

This returns a JSON response with connection counts and uptime:

{
  "status": "ok",
  "connectionCount": 3,
  "distinctConnectionCount": 2,
  "notesCount": 147
}

Add this as a dedicated health monitor in Vigilmon:

  1. URL: https://codimd.yourdomain.com/status
  2. Type: HTTP / HTTPS
  3. Expected HTTP status: 200
  4. Check interval: 1 minute

This endpoint checks more than just uptime — it confirms the application's internal state is healthy enough to report metrics.

Step 3: Monitor the Note Persistence API

CodiMD stores notes in PostgreSQL. The note API is the persistence layer for all collaborative documents. API failures mean new notes can't be created and existing notes may not save.

The note creation endpoint is available at:

GET /new

which redirects to a freshly created note. Monitor the endpoint response:

  1. URL: https://codimd.yourdomain.com/new
  2. Type: HTTP / HTTPS
  3. Expected HTTP status: 302 (redirect to the new note's URL — proves the note creation flow initiated)
  4. Check interval: 2 minutes

For API-based access (if you use CodiMD's API), probe the notes list endpoint:

GET /api/private/me/notes

This returns 401 for unauthenticated requests, confirming the API router is alive.

Step 4: Monitor the Image Upload Endpoint

CodiMD supports embedding images in markdown notes via upload. The upload endpoint is separate from the note API and typically depends on local filesystem access or an external object store (S3, MinIO).

A broken image upload breaks a common collaborative workflow — team members trying to paste screenshots into shared notes get silent failures.

Monitor the upload endpoint:

  1. URL: https://codimd.yourdomain.com/uploadimage
  2. Type: HTTP / HTTPS
  3. Expected HTTP status: 405 or 403 (POST-only endpoint; a GET returns a method error, which proves the route exists)
  4. Check interval: 5 minutes

If you use an S3-compatible backend for image storage, also monitor the backend's connectivity from your CodiMD server using a heartbeat that probes the bucket with a lightweight HEAD request.

Step 5: Monitor Database Connectivity

CodiMD's PostgreSQL connection is critical — without it, the app cannot load existing notes, save new content, or authenticate users. Add a database health check to the /status endpoint response (Step 2 already covers this), but you can also add a more specific check.

Add a custom health route to CodiMD by modifying its Express app (in lib/web/status/index.js or equivalent):

// Custom /health route
router.get('/health', async (req, res) => {
  const checks = {}

  // Check database
  try {
    await models.sequelize.authenticate()
    checks.database = 'ok'
  } catch (err) {
    checks.database = 'error'
  }

  const allOk = Object.values(checks).every(v => v === 'ok')
  res.status(allOk ? 200 : 503).json({
    status: allOk ? 'ok' : 'degraded',
    checks,
  })
})

Then monitor /health in Vigilmon with a 1 minute check interval.

Step 6: Monitor WebSocket Real-Time Collaboration

WebSocket connectivity is what makes CodiMD collaborative — without it, multiple users can't co-edit in real time. Vigilmon's HTTP monitors can't directly test WebSocket handshakes, but you can proxy-test the upgrade path:

The Socket.IO endpoint used by CodiMD for real-time collaboration is:

GET https://codimd.yourdomain.com/socket.io/?EIO=4&transport=polling

This polling transport endpoint returns a valid response even before WebSocket upgrade:

  1. URL: https://codimd.yourdomain.com/socket.io/?EIO=4&transport=polling
  2. Type: HTTP / HTTPS
  3. Expected HTTP status: 200
  4. Check interval: 1 minute

A failure here means the Socket.IO server has crashed or become unreachable, which kills real-time collaboration for all active sessions.

Step 7: Monitor Session Management

CodiMD manages user sessions via cookies and a session store (typically backed by the PostgreSQL database or Redis). Session failures lock users out even when the web server is responding normally.

Monitor the login page, which exercises the session middleware:

  1. URL: https://codimd.yourdomain.com/login
  2. Type: HTTP / HTTPS
  3. Expected HTTP status: 200
  4. Check interval: 2 minutes

If you've configured a Redis session store, also monitor Redis connectivity. Add a Redis health check to your custom /health endpoint:

// Add to the /health route
try {
  await redisClient.ping()
  checks.session_store = 'ok'
} catch (err) {
  checks.session_store = 'error'
}

Step 8: Monitor OAuth Provider Connectivity

If CodiMD is configured with OAuth authentication (GitHub, GitLab, Google, LDAP), a connectivity failure to the OAuth provider blocks all user logins — even if CodiMD itself is perfectly healthy.

For each OAuth provider, add a monitor to verify the provider's authorization endpoint is reachable:

GitHub OAuth:

  1. URL: https://github.com/login/oauth/authorize
  2. Type: HTTP / HTTPS
  3. Expected HTTP status: 200 or 302
  4. Check interval: 5 minutes

GitLab (self-hosted):

  1. URL: https://gitlab.yourdomain.com/oauth/authorize
  2. Expected HTTP status: 200 or 302
  3. Check interval: 5 minutes

Provider outages are outside your control, but knowing about them immediately helps you communicate to your team why login is failing.

Step 9: Configure Alerting

With all monitors running, configure Vigilmon alerts to reach the right people at the right time:

  1. Go to Alert Channels → add email, Slack, Microsoft Teams, or a PagerDuty integration.
  2. For the web server and /status monitors: alert on 1 failure — any downtime interrupts active collaboration sessions.
  3. For the Socket.IO endpoint: alert on 1 failure — real-time sync breaks immediately for all connected users.
  4. For image upload and OAuth provider monitors: use 2 consecutive failures to avoid false positives from transient upstream blips.
  5. For the session management monitor: alert on 1 failure — no one can log in.

Monitoring Checklist

| Service | Monitor Type | Check Interval | Alert Threshold | |---|---|---|---| | CodiMD web server | HTTP | 1 min | 1 failure | | Application status endpoint | HTTP | 1 min | 1 failure | | Note persistence API (/new) | HTTP | 2 min | 2 failures | | Image upload endpoint | HTTP | 5 min | 2 failures | | Database health | HTTP | 1 min | 1 failure | | Socket.IO real-time collaboration | HTTP | 1 min | 1 failure | | Login / session management | HTTP | 2 min | 1 failure | | OAuth provider (GitHub/GitLab) | HTTP | 5 min | 2 failures |

Conclusion

CodiMD is the tool your team reaches for during critical moments — incident response docs, sprint planning, live meeting notes. Its multi-layer architecture (Node.js, PostgreSQL, Socket.IO, OAuth) means there are more failure points than a typical single-service app. With Vigilmon covering the web server, real-time WebSocket path, note API, database, and OAuth providers, you'll have a complete picture of CodiMD's health and can restore service before a collaboration session is seriously disrupted.

Start monitoring CodiMD with Vigilmon →

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles