tutorial

Monitoring KiwiIRC with Vigilmon

KiwiIRC is a modern self-hosted web IRC client with a Node.js WebSocket proxy — here's how to monitor its frontend, proxy server, WebSocket endpoint, TLS certificates, and IRC upstream connectivity with Vigilmon.

KiwiIRC makes IRC accessible from any browser — no client installation required. But it runs as two distinct services: a web frontend (served by nginx or Apache) and a Node.js proxy server (kiwi) that bridges browser WebSocket connections to IRC servers. When either layer fails, your users see a blank page or a connection error with no context. Vigilmon lets you monitor the frontend, proxy, WebSocket endpoint, TLS certificates, and IRC upstream connectivity so you catch failures within minutes.

What You'll Set Up

  • HTTP monitor for the KiwiIRC web frontend
  • TCP port monitor for the Kiwi proxy server (port 7778)
  • WebSocket endpoint health check
  • TLS certificate expiry alert for the WebSocket domain
  • TLS certificate expiry alert for the web frontend domain
  • Cron heartbeat for the Node.js kiwi process
  • HTTP monitor for static asset availability
  • IRC upstream connectivity check via proxy

Prerequisites

  • KiwiIRC installed with the Node.js kiwi server running
  • A web server (nginx or Apache) serving the frontend assets
  • A free Vigilmon account

Step 1: Monitor the Web Frontend

The KiwiIRC static web app is served by nginx or Apache. If the web server goes down, users see a 502 or a blank page instead of the IRC client:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your KiwiIRC URL: https://irc.yourdomain.com (or http://your-server-ip if not behind TLS).
  4. Set Expected HTTP status to 200.
  5. Set Check interval to 1 minute.
  6. Click Save.

Enable Monitor SSL certificate if your frontend is served over HTTPS, and set Alert when certificate expires in less than 21 days.

Step 2: Monitor the Kiwi Proxy Server Port

The Node.js kiwi server listens on port 7778 and bridges browser WebSocket connections to upstream IRC servers. If this process dies, the browser UI loads but all IRC connections fail immediately:

  1. Click Add Monitor → TCP Port.
  2. Enter your server's IP or hostname and set Port to 7778.
  3. Set Check interval to 1 minute.
  4. Click Save.

This validates that the Node.js proxy process is listening. A closed port means the kiwi server has stopped.

If you reverse-proxy the kiwi server through nginx (common when serving both the frontend and proxy from the same domain), monitor the proxy port directly on localhost and also monitor the public-facing endpoint.

Step 3: Check the WebSocket Endpoint

Browsers connect to the Kiwi proxy via WebSocket (ws:// or wss://). A WebSocket handshake failure means the browser loads the UI but IRC connections silently fail — users see a spinner or connection error. Probe the WebSocket upgrade endpoint:

  1. Click Add Monitor → HTTP / HTTPS.
  2. The kiwi server serves the WebSocket upgrade on the same port (7778 or via reverse proxy). Set the URL to the public WebSocket path — typically https://irc.yourdomain.com/webirc/kiwiirc/.
  3. Set Expected HTTP status to 200 (the WebSocket handshake fallback responds with 200 to plain HTTP GET).
  4. Set Check interval to 2 minutes.
  5. Click Save.

If your nginx config proxies WebSocket connections, verify the upgrade headers are configured:

location /webirc/ {
    proxy_pass http://127.0.0.1:7778;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Step 4: TLS Certificate Expiry for the WebSocket Domain

Browsers enforce TLS for WebSocket connections on HTTPS pages — an expired certificate on wss:// breaks all IRC connections even if the HTTP frontend is still serving correctly:

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

If the WebSocket domain is the same as the frontend domain, this is already covered by the Step 1 certificate monitor. If they're on separate hostnames, configure both.

Verify your certificate renewal hook renews and reloads both endpoints:

# /etc/letsencrypt/renewal-hooks/deploy/kiwiirc.sh
#!/bin/bash
nginx -s reload
# If kiwi server uses its own cert path:
cp /etc/letsencrypt/live/irc.yourdomain.com/fullchain.pem /etc/kiwiirc/ssl/fullchain.pem
cp /etc/letsencrypt/live/irc.yourdomain.com/privkey.pem   /etc/kiwiirc/ssl/privkey.pem
systemctl reload kiwiirc || true

Step 5: Monitor the Node.js Kiwi Process with a Heartbeat

Port availability doesn't guarantee the kiwi server is healthy — the process could be running but stuck or failing to proxy connections. A heartbeat catches deeper failures:

  1. In Vigilmon, click Add Monitor → Cron Job / Heartbeat.
  2. Set Expected interval to 5 minutes.
  3. Copy the heartbeat URL.

Add a cron job:

# /etc/cron.d/kiwiirc-heartbeat
*/5 * * * * root pgrep -f "node.*kiwiirc" > /dev/null && \
  curl -fsS --retry 3 https://vigilmon.online/ping/your-heartbeat-id

Adjust the pgrep pattern to match how you launch the kiwi server. If you use pm2 to manage the process:

*/5 * * * * root pm2 list | grep -q "kiwiirc.*online" && \
  curl -fsS https://vigilmon.online/ping/your-heartbeat-id

To auto-restart the kiwi process on failure, use systemd:

[Unit]
Description=KiwiIRC Proxy Server
After=network.target

[Service]
User=kiwiirc
WorkingDirectory=/opt/kiwiirc
ExecStart=/usr/bin/node /opt/kiwiirc/server/index.js --config /etc/kiwiirc/config.conf
Restart=on-failure
RestartSec=10

[Install]
WantedBy=multi-user.target

Step 6: Monitor IRC Upstream Connectivity

The kiwi proxy must be able to reach configured upstream IRC servers. If those IRC servers are unreachable from your kiwi host (network change, firewall update, IRC server down), every IRC connection attempt through KiwiIRC will fail. Monitor the upstream IRC server directly from your monitoring perspective:

  1. Click Add Monitor → TCP Port.
  2. Enter the upstream IRC server's hostname and set Port to 6667 (plain) or 6697 (TLS).
  3. Set Check interval to 2 minutes.
  4. Click Save.

This validates that the IRC server is reachable — not that the kiwi proxy can reach it (which may differ if the kiwi server is on a different network segment). For full validation, add a connectivity check from the kiwi host itself:

# /etc/cron.d/kiwi-upstream-check
*/5 * * * * root nc -zw5 irc.upstream.com 6697 && \
  curl -fsS https://vigilmon.online/ping/your-upstream-heartbeat-id

Step 7: Monitor Static Asset Availability

KiwiIRC's JavaScript bundle, CSS, and fonts are served as static assets. A broken asset path (permissions change, nginx misconfiguration, missing file after an update) causes the IRC client UI to render partially or not at all:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set the URL to the main JavaScript bundle path, e.g., https://irc.yourdomain.com/static/kiwiirc.js (check your nginx config or the KiwiIRC install path for the exact filename).
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 10 minutes.
  5. Click Save.

Optionally add a second check for the CSS file. These rarely fail but catch the class of mistake where a deployment updates files in the wrong directory.

Step 8: Monitor Theme and Plugin Assets

If you use custom KiwiIRC themes or plugins served from the same web server, a 404 on a theme asset degrades the UI:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set the URL to your custom theme's CSS or JS path.
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 10 minutes.
  5. Click Save.

For plugin URLs loaded from external CDNs or your own asset server, add separate monitors so you catch a CDN outage that's degrading your KiwiIRC instance.

Step 9: Configure Alerts

  1. Go to Settings → Alerts in Vigilmon.
  2. Add a Slack webhook or email channel.
  3. Set 2 consecutive failures as the alert threshold to reduce transient false positives.
  4. Apply the alert profile to all KiwiIRC monitors.

Recommended alert priority:

| Monitor | Priority | User impact | |---|---|---| | Web frontend | Critical | No IRC access at all | | Kiwi proxy port 7778 | Critical | IRC connections impossible | | WebSocket endpoint | Critical | Connections fail silently | | Node.js process heartbeat | Critical | Proxy dead | | Frontend TLS cert | High | Browser blocks HTTPS | | WebSocket TLS cert | High | wss:// blocked by browsers | | IRC upstream connectivity | High | All IRC connections fail | | Static assets | Medium | UI partially broken | | Theme/plugin assets | Low | Cosmetic degradation |

What to Watch

| Monitor | Type | Check | Alert threshold | |---|---|---|---| | Web frontend | HTTP | HTTPS 200 at / | 1 failure | | Kiwi proxy port | TCP | Port 7778 open | 1 failure | | WebSocket endpoint | HTTP | /webirc/ responds 200 | 1 failure | | Node.js process | Heartbeat | Cron ping every 5 min | 2 missed | | Frontend TLS cert | SSL | Expiry < 21 days | Immediate | | WebSocket TLS cert | SSL | Expiry < 21 days | Immediate | | IRC upstream | TCP | Port 6667/6697 open | 2 failures | | Static JS bundle | HTTP | Asset URL 200 | 2 failures | | Theme/plugin assets | HTTP | Asset URL 200 | 3 failures |

Conclusion

KiwiIRC runs as two cooperating services — lose either and your users can't connect to IRC at all. Vigilmon's multi-layer monitoring covers the frontend, the Node.js proxy, the WebSocket endpoint, and the upstream IRC server so you find out within minutes, not when users start complaining. The free Vigilmon tier covers all the monitors set up here.

Sign up for Vigilmon free →

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