tutorial

Monitoring Spacedeck with Vigilmon

Spacedeck is a self-hosted collaborative whiteboard — but a crashed Node process, a disconnected Redis session store, or a stale WebSocket means your team loses real-time co-editing silently. Here's how to monitor every layer with Vigilmon.

Spacedeck is an open-source collaborative whiteboard that lets multiple users draw, annotate, and edit together in real time — a self-hosted alternative to Miro or Mural. When you run it yourself, you own every layer: the Node.js web server, the PostgreSQL database that persists whiteboard objects and user accounts, the Redis session store, the WebSocket upgrade path that powers live collaboration, and the export and thumbnail pipelines. A failure in any one of these can silently block your team from accessing or editing boards. Vigilmon gives you HTTP uptime monitoring, TCP port probes, WebSocket health checks, cron heartbeats, and TLS certificate alerts to cover every layer.

What You'll Set Up

  • HTTP uptime monitor for the Spacedeck web interface (port 9666)
  • PostgreSQL database TCP connectivity probe
  • Redis session store TCP connectivity probe
  • WebSocket handshake health check
  • Deck creation and retrieval API endpoint checks
  • File export service health (PNG/SVG export)
  • Thumbnail generation endpoint check
  • Session cleanup cron heartbeat
  • SSL/TLS certificate expiry alert

Prerequisites

  • Spacedeck running and reachable over HTTP/HTTPS (default port 9666)
  • PostgreSQL and Redis running on the same host or a known address
  • A free Vigilmon account

Step 1: Monitor the Spacedeck Web Interface

The Node.js process is the outermost entry point. If it crashes or the reverse proxy in front of it stops routing traffic, every user sees a blank page or connection refused.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Spacedeck URL: https://whiteboard.yourdomain.com (or http://your-server-ip:9666 for a direct install).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

If Spacedeck exposes a /health route, point the monitor there — it provides a richer signal by verifying internal wiring, not just that the process is listening.

Step 2: Monitor PostgreSQL Database Connectivity

Spacedeck stores whiteboard objects, user accounts, deck metadata, and shape data in PostgreSQL. A database outage means users cannot load, save, or share boards.

  1. Click Add Monitor → TCP Port.
  2. Host: your PostgreSQL server hostname or IP.
  3. Port: 5432.
  4. Check interval: 1 minute.
  5. Click Save.

For a deeper application-layer check, add a lightweight health endpoint to Spacedeck's reverse proxy or a companion script that runs a SELECT 1 query and returns {"status":"ok"}. Point a second HTTP monitor at it with Expected body contains set to ok.

Step 3: Monitor Redis Session Store Connectivity

Spacedeck uses Redis to store user session data. If Redis becomes unreachable, authenticated users are logged out and new logins fail — boards appear to load but collaborative features stop working because the server cannot validate sessions.

  1. Click Add Monitor → TCP Port.
  2. Host: your Redis server hostname or IP.
  3. Port: 6379.
  4. Check interval: 1 minute.
  5. Click Save.

If Redis is password-protected or running on a non-standard port, update the host and port fields accordingly.

Step 4: Monitor WebSocket Connection Health

Spacedeck's real-time collaboration is driven by a persistent WebSocket connection. Without it, changes from one user do not appear on other users' screens until they reload. A reverse proxy misconfiguration or a missing Upgrade header silently disables co-editing while the HTTP interface still loads.

Add an HTTP monitor that validates the WebSocket upgrade response:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://whiteboard.yourdomain.com (the same origin Spacedeck uses for its WebSocket handshake).
  3. Set Expected HTTP status to 101 — or 200 if your proxy terminates WebSocket upgrade probes at the root level.
  4. Alternatively, monitor the endpoint that the client polls during the handshake negotiation (check your Spacedeck version's network tab to confirm the path, typically /socket.io/ or a similar namespace).
  5. Check interval: 2 minutes.
  6. Click Save.

A sustained failure here with the web interface still responding is a proxy misconfiguration, not a Spacedeck crash — the distinction helps you triage faster.

Step 5: Monitor the Deck API Endpoint

The deck creation and retrieval API is the core application path. Probe it to confirm Spacedeck can serve board data end-to-end:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://whiteboard.yourdomain.com/api/spaces (the spaces list endpoint, which requires a valid session).
  3. Set Expected HTTP status to 200 or 401 — either response confirms the API process is alive and routing requests; a 502 or 504 means the backend is down.
  4. Check interval: 5 minutes.
  5. Click Save.

A 401 is acceptable here because the monitor makes an unauthenticated request — the important thing is that Spacedeck's API process is responding, not that it grants access.

Step 6: Monitor the File Export Service

Spacedeck supports exporting whiteboards to PNG and SVG. This pipeline runs a headless rendering process. If it crashes or its dependencies (fonts, canvas library bindings) are broken, export requests hang or return errors — often without affecting the rest of the UI.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://whiteboard.yourdomain.com/api/spaces/YOUR_CANARY_DECK_ID/export.png — replace with a small test deck you keep as a canary.
  3. Set Expected HTTP status to 200.
  4. Set Expected body contains or leave empty (Vigilmon will alert on non-200 status).
  5. Check interval: 10 minutes.
  6. Click Save.

Keep the canary deck small (a single shape) so the export completes quickly and does not inflate response-time metrics.

Step 7: Monitor the Thumbnail Generation Service

Spacedeck generates thumbnail previews for decks shown in the dashboard grid. A broken thumbnail service leaves the dashboard showing placeholder icons, which makes it harder for users to identify boards. Like the export service, thumbnail generation runs a separate rendering path.

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://whiteboard.yourdomain.com/api/spaces/YOUR_CANARY_DECK_ID/thumbnail.png.
  3. Set Expected HTTP status to 200.
  4. Check interval: 15 minutes.
  5. Click Save.

Step 8: Session Cleanup Cron Heartbeat

Spacedeck runs a scheduled job to purge expired sessions and orphaned workspace data. If this job stops running, stale session records accumulate in the database and Redis, potentially causing login slowdowns or storage bloat.

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set the expected ping interval to match your cleanup schedule (e.g. 60 minutes).
  3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/YOUR_TOKEN.
  4. Add the ping to your cleanup script or cron entry:
# /etc/cron.d/spacedeck-cleanup
0 * * * * spacedeck node /opt/spacedeck/cleanup.js && curl -s https://vigilmon.online/heartbeat/YOUR_TOKEN

If Spacedeck handles cleanup internally via a scheduled timer, wrap the Spacedeck process restart or reload that triggers cleanup:

# After scheduled restart
curl -s https://vigilmon.online/heartbeat/YOUR_TOKEN

If the job stalls or the host cron daemon dies, Vigilmon alerts you before users report stale data.

Step 9: SSL/TLS Certificate Expiry

Collaborative tools accessed from browsers are especially sensitive to certificate errors — a lapsed certificate locks out every user simultaneously.

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

Step 10: 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 interface monitor — a single slow check is noise; two consecutive failures mean something is actually wrong.
  3. Route PostgreSQL, Redis, and WebSocket alerts to a higher-urgency channel — these failures are not self-healing and directly break collaboration for all active users.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP — web interface | https://whiteboard.yourdomain.com | Node.js process crash, proxy failure | | TCP — PostgreSQL | :5432 | Database process down, connection refused | | TCP — Redis | :6379 | Session store unreachable, logins failing | | HTTP — WebSocket handshake | /socket.io/ | Real-time collaboration disabled | | HTTP — Deck API | /api/spaces | API process down, routing broken | | HTTP — File export | /api/spaces/ID/export.png | Export pipeline crash | | HTTP — Thumbnail | /api/spaces/ID/thumbnail.png | Thumbnail renderer broken | | Cron heartbeat | cleanup script | Session/data cleanup job failure | | SSL certificate | whiteboard domain | TLS renewal failure |

Self-hosting Spacedeck means owning the full collaboration stack — from the Node.js server to the PostgreSQL schema to the Redis session cache to the WebSocket upgrade path. With Vigilmon watching each layer, you catch a crashed export renderer before users report missing downloads, a Redis outage before everyone gets logged out, and a WebSocket misconfiguration before your team's co-editing silently degrades to a refresh-and-hope workflow.

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