Monitoring tldraw with Vigilmon

tldraw is an open-source collaborative whiteboard you can self-host, giving your team infinite canvases without relying on a SaaS vendor. That self-hosted freedom means you own the uptime — when the tldraw server crashes, everyone editing a shared canvas loses their session simultaneously. Vigilmon keeps watch on your tldraw instance so you catch failures before your team does.

What You'll Set Up

• HTTP uptime monitor for the tldraw web application
• API health check for the tldraw backend
• WebSocket connectivity check for real-time collaboration
• SSL certificate expiry alerts for your tldraw domain

Prerequisites

• tldraw self-hosted instance running (Docker or Node.js)
• tldraw accessible over HTTP or HTTPS on a domain or IP
• A free Vigilmon account

Step 1: Monitor the tldraw Web Application

The tldraw frontend is the canvas your users interact with. If this endpoint is unreachable, no one can load or create boards.

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

If tldraw is running behind a reverse proxy (nginx, Caddy, Traefik), the HTTP check confirms both the proxy and the tldraw process are healthy. A 502 Bad Gateway response means tldraw itself has crashed even though the proxy is still listening.

Step 2: Check the tldraw API Health Endpoint

The tldraw server exposes a health endpoint that confirms the backend process is running and its internal services are reachable. Add a dedicated API monitor:

1. Add Monitor → HTTP / HTTPS.
2. URL: https://tldraw.yourdomain.com/api/health (or /health depending on your deployment configuration).
3. Set Expected HTTP status to 200.
4. Under Advanced, set Expected body contains to ok or "status":"ok" to verify the response payload, not just the HTTP code.
5. Set Check interval to 1 minute.
6. Click Save.

If your tldraw deployment does not expose a dedicated health route, add one. In a custom tldraw server (apps/dotcom-worker or a standalone Express wrapper), add:

app.get('/api/health', (req, res) => {
  res.json({ status: 'ok', timestamp: new Date().toISOString() });
});

A health endpoint that verifies database connectivity (if you've added persistence) gives you a richer signal than a static response.

Step 3: Monitor WebSocket Availability

tldraw's real-time collaboration runs over WebSockets. The HTTP endpoint being up does not guarantee the WebSocket server is accepting connections — the WS handler and the HTTP server often run as separate processes or on separate ports.

Use Vigilmon's TCP port check to confirm the WebSocket port is open:

1. Add Monitor → TCP Port.
2. Host: tldraw.yourdomain.com, Port: 443 (WebSocket over TLS) or the port your tldraw WS server listens on.
3. Set Check interval to 2 minutes.
4. Click Save.

For a more targeted check, add a keyword monitor on the tldraw URL to confirm the page's JavaScript bundle loads — if the WS upgrade is broken, the browser console will show errors but the HTTP status will still be 200:

1. Open the HTTP / HTTPS monitor for your tldraw URL.
2. Under Advanced, set Expected body contains to tldraw (a string present in every tldraw HTML page).
3. Click Save.

Step 4: Add SSL Certificate Monitoring

tldraw sessions are only secure over HTTPS. A lapsed certificate will lock out all users with an untrusted certificate browser error — often harder to recover from than a simple downtime because users may not know to report it.

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

With a 21-day lead time, you have three weeks to renew or investigate Let's Encrypt auto-renewal failures before your users see a certificate error page.

Step 5: Heartbeat Monitoring for tldraw Background Workers

If your tldraw deployment includes persistence workers, room cleanup jobs, or scheduled snapshot exports, use Vigilmon's cron heartbeat to confirm these background processes are running.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to match your worker schedule (e.g. 60 minutes for an hourly cleanup job).
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Add the ping to the end of your worker script:

#!/bin/bash
node scripts/cleanup-old-rooms.js
curl -s https://vigilmon.online/heartbeat/abc123

Or in a Node.js worker:

import https from 'https';

async function runCleanup() {
  await cleanupExpiredRooms();
  https.get('https://vigilmon.online/heartbeat/abc123');
}

If the worker crashes before pinging, 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 endpoint.
2. Set Consecutive failures before alert to 2 on the main tldraw monitor — Docker restarts and process recycling can cause a single probe miss.
3. Use Maintenance windows in Vigilmon to suppress alerts when deploying a new tldraw version:

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

docker pull tldraw/tldraw && docker compose up -d

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web application | https://tldraw.yourdomain.com | Frontend down, proxy failure | | API health | /api/health | Backend process crash | | TCP port | :443 | WebSocket server unreachable | | SSL certificate | tldraw domain | Certificate renewal failure | | Cron heartbeat | Heartbeat URL | Background worker crash |

tldraw turns your self-hosted server into a collaborative workspace — but self-hosted means you own the reliability. With Vigilmon watching the HTTP frontend, API health, WebSocket port, and SSL certificate, you'll know about failures in real time instead of hearing about them from a frustrated team member mid-session.