tutorial

Monitoring Hydrogen Web with Vigilmon

Hydrogen Web is a minimal Matrix client built as a static SPA — but its web server, Matrix homeserver API, and push notification relay can all fail silently. Here's how to monitor every layer with Vigilmon.

Hydrogen Web is an open source Matrix client built from scratch — minimal, fast, and designed to work on older hardware and slow connections. Like all Matrix clients, it runs entirely in the browser as a static SPA (TypeScript/Preact served via any static web server) and relies on a Matrix homeserver for all data. That lightweight architecture means most of Hydrogen's functionality — IndexedDB message caching, Service Worker offline mode, session state — lives in the browser and cannot be probed server-side. But the pieces you can monitor server-side matter enormously: the static web server, the Matrix homeserver API, TLS certificates, and the push notification relay. Vigilmon covers all of these from a single dashboard.

What You'll Set Up

  • Static web server (nginx/Caddy) availability monitoring
  • Static asset serving health (JS/CSS bundle response time)
  • Matrix homeserver API connectivity monitoring (/_matrix/client/r0)
  • TLS certificate expiry for both the Hydrogen hosting domain and the Matrix server domain
  • Push notification relay (UnifiedPush/NTFY/Sygnal) health monitoring
  • TCP port monitoring for WebSocket connectivity

Prerequisites

  • Hydrogen Web deployed and served over HTTPS (any static file server)
  • A Matrix homeserver reachable from your deployment
  • A free Vigilmon account

Step 1: Monitor the Static Web Server Availability

Hydrogen's entire client is static files — HTML, JS bundles, CSS, and assets. If the web server goes down or returns errors, no one can load the client.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Hydrogen URL: https://hydrogen.yourdomain.com.
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Enable Monitor SSL certificate and set Alert when certificate expires in less than 21 days.
  7. Click Save.

This catches nginx/Caddy/Apache crashes, server reboots, firewall rule changes, and Let's Encrypt renewal failures for the Hydrogen domain.

Step 2: Monitor Static Asset Serving Health

Hydrogen's JS bundle is the entire application. A missing bundle or a misconfigured MIME type (Content-Type served as text/plain instead of application/javascript) causes a blank client even when the root URL returns 200.

Locate the main bundle path in Hydrogen's build output (typically hydrogen.es2019.js or similar):

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://hydrogen.yourdomain.com/assets/hydrogen.es2019.js (adjust to your actual build output path).
  3. Expected HTTP status: 200.
  4. Check interval: 5 minutes.
  5. Set Response time threshold to 3000ms — Hydrogen's fast-load promise depends on fast asset delivery.
  6. Click Save.

Check the current bundle filename from your deployed Hydrogen's index.html <script> tag — the filename may include a content hash that changes on upgrades.

Step 3: Monitor Matrix Homeserver API Connectivity

Hydrogen connects to your Matrix homeserver at runtime using the Matrix client-server API. If the homeserver is unreachable, users can load the client but cannot authenticate, sync messages, or send anything.

Monitor the homeserver's client-server API health:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://matrix.yourdomain.com/_matrix/client/versions
  3. Expected HTTP status: 200.
  4. Check interval: 1 minute.
  5. Click Save.

The /_matrix/client/versions response confirms the homeserver is alive and advertising its supported Matrix spec versions. Add a second monitor for the legacy r0 prefix that Hydrogen uses:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://matrix.yourdomain.com/_matrix/client/r0/login
  3. Expected HTTP status: 200.
  4. Check interval: 5 minutes.
  5. Click Save.

Step 4: TLS Certificate Expiry for Both Domains

Hydrogen depends on two TLS certificates: one for its static hosting domain and one for the Matrix homeserver. Either expiring completely blocks users.

Hydrogen hosting domain — already covered by enabling SSL monitoring in Step 1.

Matrix homeserver domain — add a dedicated monitor:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://matrix.yourdomain.com/_matrix/client/versions.
  3. Enable Monitor SSL certificate.
  4. Alert when certificate expires in less than: 21 days.
  5. Click Save.

21 days gives you enough time to investigate certificate renewal failures and manually rotate if auto-renewal is broken.

Step 5: Monitor Service Worker and Offline Mode

Hydrogen aggressively uses Service Workers for offline functionality and performance. The Service Worker is registered from a specific URL path — if that script is missing or returns an error, offline mode breaks for all users who have registered it.

Monitor the Service Worker script:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://hydrogen.yourdomain.com/sw.js (or the path referenced in Hydrogen's index.html serviceWorker.register() call).
  3. Expected HTTP status: 200.
  4. Check interval: 5 minutes.
  5. Click Save.

Server-side limits: Service Worker registration state, IndexedDB storage, and offline cache are entirely in the browser. They cannot be probed by an external monitor. Document this in your runbook: if users report losing cached messages after a browser update, the cause is browser-side, not server-side.

Step 6: Monitor Push Notification Relay Health

Hydrogen supports UnifiedPush-compatible push gateways (NTFY, Sygnal) for mobile and desktop push notifications. If the relay is down, users stop receiving push alerts for new messages.

For NTFY:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://ntfy.yourdomain.com/ (or your NTFY server root).
  3. Expected HTTP status: 200.
  4. Check interval: 5 minutes.
  5. Click Save.

For Sygnal:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://sygnal.yourdomain.com/_matrix/push/v1/notify.
  3. Expected HTTP status: 405 (GET is not supported by Sygnal's notify endpoint — a 405 confirms the service is running).
  4. Check interval: 5 minutes.
  5. Click Save.

Step 7: Monitor WebSocket Connectivity via TCP

Matrix clients maintain long-lived WebSocket connections for real-time sync. A firewall rule change or reverse proxy misconfiguration can block WebSocket upgrades while leaving HTTPS working — clients appear to connect but never receive new messages.

  1. Click Add Monitor → TCP Port.
  2. Hostname: matrix.yourdomain.com.
  3. Port: 443.
  4. Check interval: 2 minutes.
  5. Click Save.

If you run Synapse with the federation listener on a separate port (default 8448), add a second TCP monitor for that port.

Step 8: 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 for the web server monitor to tolerate brief nginx restarts.
  3. Set it to 1 for the Matrix API monitor — a single failure means your homeserver is offline and all users are disconnected.
  4. Use Maintenance windows when updating Hydrogen (static deployments are fast but not instant):
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "MONITOR_ID", "duration_minutes": 5}'

What You Cannot Monitor Server-Side

Hydrogen's browser-side components are outside the reach of external monitoring. Document these in your runbook:

  • IndexedDB message cache — stored in the browser; cannot be probed externally. If users report missing messages after a browser update, the fix is browser-side.
  • Service Worker cache state — registered per-browser; a sw.js 200 response confirms the script is available but not that it's cached or active in any given browser.
  • Cross-platform session persistence — Hydrogen's session tokens are stored in browser storage; token expiry or storage clearing requires users to log back in.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web server uptime | https://hydrogen.yourdomain.com | nginx/Caddy crash, network outage | | JS bundle serving | /assets/hydrogen.es2019.js | Missing bundle, broken server config | | Matrix API health | /_matrix/client/versions | Homeserver crash, API unavailable | | Matrix r0 API | /_matrix/client/r0/login | Legacy API endpoint failure | | Matrix domain SSL | Homeserver domain | Matrix TLS certificate expiry | | Service Worker script | /sw.js | Offline mode broken for new users | | Push relay (NTFY) | NTFY server root | Push notifications stopped | | Push relay (Sygnal) | Sygnal notify endpoint | Push gateway unreachable | | WebSocket TCP | matrix.yourdomain.com:443 | WebSocket upgrades blocked | | SSL certificate | Hydrogen domain | Let's Encrypt renewal failure |

Hydrogen Web's minimal architecture means its server-side footprint is small — but that simplicity doesn't protect against the web server going down, the Matrix homeserver becoming unreachable, or TLS certificates expiring. With Vigilmon monitoring both domains' certificates, the Matrix API, static asset delivery, and push relay, you'll catch every server-side failure and know exactly which layer to restore.

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