Monitoring Grist with Vigilmon: Health Endpoint, Document API & SSL Alerts

Grist is a powerful open-source spreadsheet-database hybrid — think Airtable meets Excel, fully self-hosted. Teams use it to manage project data, build internal tools, and run formulas over structured datasets. When Grist goes down, those internal tools go with it. Vigilmon ensures you're the first to know about a Grist outage — not your users. In this tutorial you'll set up monitoring for the Grist health endpoint, web UI, document storage API, and SSL certificate.

What You'll Build

A Vigilmon HTTP monitor for Grist's health endpoint
A web UI availability check
A document API monitor that validates document access
SSL certificate expiry alerts
Slack and email alert channels

Prerequisites

A running Grist instance (Docker is the recommended deployment)
Grist accessible at a public or VPN-routable URL
A free Vigilmon account

Step 1: Monitor the Health Endpoint

Grist exposes a health endpoint at /status that returns a JSON response indicating the server's state. By default Grist runs on port 8484.

curl https://grist.yourdomain.com/status
# {"status":"ok","version":"1.1.x"}

In Vigilmon, create a new HTTP Monitor:

| Field | Value | |---|---| | URL | https://grist.yourdomain.com/status | | Method | GET | | Check interval | 60 seconds | | Expected status | 200 | | Keyword match | "ok" | | Timeout | 10 seconds | | Regions | 2–3 for redundancy |

The keyword match on "ok" catches the case where Grist returns a 200 with a degraded or error status body. This monitor fires within 60 seconds of a Grist process crash, database failure, or disk exhaustion.

Step 2: Web UI Availability Check

The Grist web UI is served by the same Node.js process as the API, but a routing or static asset misconfiguration can break the UI while leaving the health endpoint intact. Add a separate monitor for the login page:

| Field | Value | |---|---| | URL | https://grist.yourdomain.com | | Method | GET | | Expected status | 200 | | Keyword match | Grist | | Check interval | 5 minutes |

If you use SAML or a third-party SSO provider (Google OAuth, OIDC), the root URL may redirect to your identity provider — adjust the keyword to match content on the IdP login page, or point the monitor at a Grist page that is directly accessible (e.g. /welcome).

Step 3: Document Storage API Monitor

Grist documents are the core product — if document reads or writes fail, users can't do their work. Grist stores documents as SQLite files on disk (or in S3 when configured for object storage). A full disk or broken S3 credentials can cause document operations to fail while the health endpoint still returns 200.

To monitor document availability, create an HTTP monitor that calls the Grist API to list documents in a workspace. First, generate a Grist API key:

Then create a Vigilmon HTTP monitor with an API key header:

| Field | Value | |---|---| | URL | https://grist.yourdomain.com/api/workspaces | | Method | GET | | Expected status | 200 | | Keyword match | workspaces | | Headers | Authorization: Bearer YOUR_GRIST_API_KEY | | Check interval | 5 minutes |

Store the API key in Vigilmon's secrets manager rather than in plain text. This check validates that:

The Grist API routing is working
The database backing workspace metadata is readable
Authentication middleware is functioning

If you host Grist on a private network, you can run this check from a Vigilmon internal probe agent, or use a cron job on the same network that pings Vigilmon's heartbeat endpoint on success.

Step 4: SSL Certificate Expiry Alerts

Grist users often leave long-running spreadsheet sessions open. A surprise certificate expiry causes a jarring mixed-content error mid-session. Enable SSL monitoring on your health endpoint monitor in Vigilmon:

| Field | Value | |---|---| | Alert when expiry < | 21 days | | Alert again at | 7 days |

If you're managing certificates with Let's Encrypt (Certbot or acme.sh), these alerts catch auto-renewal failures before users are affected. For custom CA certificates used in enterprise deployments, 21 days is enough lead time to request and install a replacement.

Step 5: Alert Routing

Email

Vigilmon → Alert Channels → Email → assign to all monitors.

Slack

Generate an incoming webhook in your Slack workspace
Vigilmon → Alert Channels → Add Channel → Webhook → paste the URL
Assign to your health, UI, and document API monitors

A sample Grist alert message:

🔴 *grist.yourdomain.com/status* is DOWN
Status: 503 | Duration: 2m 20s
Check disk space: df -h /grist-data
Check container: docker logs grist

Docker Health Check

If you're running Grist in Docker, add a native health check to your Compose file so Docker itself restarts unhealthy containers:

services:
  grist:
    image: gristlabs/grist:latest
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8484/status"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 15s
    environment:
      - APP_HOME_URL=https://grist.yourdomain.com
      # ... other env vars ...

This pairs with Vigilmon: Docker restarts unhealthy processes, Vigilmon alerts you when restarts are happening or when the container can't recover.

Production Checklist

[ ] /status health monitor with keyword match on "ok"
[ ] Web UI availability check every 5 minutes
[ ] Document API monitor with API key header configured
[ ] Docker healthcheck set in Compose config
[ ] SSL expiry alert at 21 days
[ ] Alert channels tested end-to-end

Wrapping Up

Grist's reliability matters because teams build workflows on top of it — a silent outage stops work across multiple teams simultaneously. With Vigilmon you now have:

Process health: /status polled every 60 seconds
UI availability: login page checked every 5 minutes
Document API: workspace list validated to confirm data layer is healthy
SSL: expiry alerts before certs lapse

The document API check is the most valuable — it's the one check that can catch a full disk or broken storage config before your users encounter "Error loading document."