How to Monitor Your AFFiNE Instance with Vigilmon

AFFiNE is a powerful open-source alternative to Notion — combining docs, whiteboards, and databases in one self-hosted workspace. Its real-time collaboration relies on a WebSocket sync server backed by Node.js and PostgreSQL. When the sync server drops, users see stale content and lose the ability to collaborate in real time. Vigilmon monitors the entire AFFiNE stack so you know about failures before your team notices that their edits aren't syncing.

What You'll Set Up

• Vigilmon HTTP monitor for the AFFiNE web UI
• A health endpoint check confirming the AFFiNE backend is responding
• A sync server availability check
• SSL certificate expiry alerts

Prerequisites

• A self-hosted AFFiNE instance (Docker Compose recommended, version 0.18+)
• A free Vigilmon account
• Shell access to the AFFiNE host

Why AFFiNE Monitoring Matters

AFFiNE's self-hosted deployment consists of at least three layers: the web frontend (served by a Node.js server), the GraphQL API backend, and a real-time sync server that handles WebSocket connections for collaborative editing. Optionally, a blob storage backend handles uploaded files. A failure in any of these layers results in a different kind of user-visible breakage — 404 pages, failed logins, or silent sync failures. Standard uptime monitoring only catches the most obvious of these failures (a dead web server).

Vigilmon's combination of HTTP monitoring and health endpoint probing covers all the layers that matter.

Step 1: Monitor the AFFiNE Web UI

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

This checks that the Node.js frontend server and your reverse proxy are serving the AFFiNE web application.

Step 2: Monitor the AFFiNE Health Endpoint

AFFiNE's backend exposes a health check at /api/worker-health (or /health depending on version). This endpoint confirms the backend service and its database connection are alive:

1. In Vigilmon, click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter https://affine.yourdomain.com/api/worker-health.
4. Set Expected status code to 200.
5. Set Name to AFFiNE – Backend Health.
6. Click Save.

If you are on an older AFFiNE release or a custom build, verify the health endpoint path by checking the AFFiNE container logs:

docker compose logs affine | grep -i health

Adjust the URL accordingly. The response is typically {"status":"ok"} or a simple 200 OK with no body — either is sufficient for Vigilmon to confirm the backend is alive.

Step 3: Monitor the Sync Server

AFFiNE's collaborative sync layer runs on a separate internal port (default 3010) and is typically proxied through your reverse proxy under a subpath such as /collaboration/. This is the most failure-prone component because it depends on both the backend service and the database simultaneously.

Check how your reverse proxy exposes the sync server. For a typical nginx setup:

location /collaboration/ {
    proxy_pass http://localhost:3010/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

The sync server usually provides a health or version route at its root. Add a Vigilmon monitor:

1. In Vigilmon, click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter https://affine.yourdomain.com/collaboration/.
4. Set Expected status code to 200 or 404 — even a 404 confirms the proxy is routing to the sync server. A 502 means the sync container is down.
5. Set Name to AFFiNE – Sync Server.
6. Click Save.

If you prefer a TCP-level check and your sync server is not proxied through HTTPS:

1. Add a TCP monitor in Vigilmon.
2. Enter your server hostname and port 3010.
3. Set Name to AFFiNE – Sync TCP.
4. Click Save.

The TCP monitor confirms the sync process is listening even before testing the HTTP layer above it.

Step 4: Add a Custom Health Script (Optional)

For a deeper database + Redis check, add a small shell script to your AFFiNE Docker Compose setup:

#!/bin/bash
# /opt/affine/health-check.sh
set -euo pipefail

HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_TOKEN"

# Check that AFFiNE backend responds
HTTP_STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  http://localhost:3000/api/worker-health --max-time 5)

if [ "$HTTP_STATUS" = "200" ]; then
  curl -fsS --retry 3 "$HEARTBEAT_URL" > /dev/null 2>&1
else
  echo "AFFiNE health check failed: HTTP $HTTP_STATUS" >&2
fi

Schedule it with cron:

*/5 * * * * /opt/affine/health-check.sh

This script-level check adds defense-in-depth: the heartbeat only fires when the backend is actively healthy, not just when the container is running.

Step 5: Configure Response Time Alerts

AFFiNE pages that load large workspaces or render complex whiteboards can be slow if the database is under pressure.

1. Open your AFFiNE web UI monitor in Vigilmon.
2. Find Response time threshold.
3. Set Warn to 1200ms and Critical to 4000ms.
4. Save.

Step 6: Enable SSL Certificate Monitoring

AFFiNE's sync server uses WebSocket over TLS (wss://). An expired certificate breaks real-time collaboration for all users without affecting the web UI's ability to load cached content — making this failure invisible to a simple HTTP check.

1. Open your primary AFFiNE monitor in Vigilmon.
2. Enable Alert when certificate expires within 14 days.
3. Save.

Repeat for the sync server monitor if it uses a separate domain or subdomain.

Step 7: Configure Notifications

1. Go to Alert Channels → Add Channel → Slack webhook (or email).
2. Paste your Slack webhook URL with a payload:

{
  "text": "📝 *{{monitor_name}}* is {{status}}!\nURL: {{url}}\nTime: {{timestamp}}"
}

3. Attach the channel to all your AFFiNE monitors.

Step 8: Verify the Full Setup

1. Test the UI monitor: Temporarily change your monitor URL to a non-existent path and confirm the alert fires.
2. Test the sync monitor: Stop the AFFiNE sync container (docker compose stop affine) and confirm the sync monitor alerts within 2 minutes. Restart and confirm recovery.
3. Review the dashboard: Check Vigilmon's response time history to establish a baseline for your AFFiNE workspace's normal load times.

Going Further

• Blob storage monitoring: If AFFiNE is configured with S3-compatible storage for uploaded files, add a monitor for your storage bucket's health endpoint to catch file upload failures before users report broken images.
• Database TCP check: Add a TCP monitor for your PostgreSQL port (default 5432) so database crashes surface immediately rather than waiting for the health endpoint to time out.
• Status page: Embed a Vigilmon status badge in your team's internal documentation so everyone can quickly check AFFiNE's health without asking in Slack.
• Alert escalation: Use Vigilmon's notification channels to page an on-call engineer via PagerDuty or OpsGenie when the sync server goes down — collaboration loss is high-impact for any team that relies on AFFiNE for daily work.

With Vigilmon covering the web UI, backend health, sync server, and SSL certificates, your AFFiNE workspace is monitored end-to-end — so you'll always be the first to know when something needs your attention.