tutorial

Monitoring Convos IRC Client with Vigilmon

Convos is a self-hosted persistent web IRC client built on Perl/Mojolicious — here's how to monitor its web server, WebSocket connections, PostgreSQL database, and TLS certificates with Vigilmon.

Convos is the self-contained IRC client you can run on your own server — a single-page web app with a Mojolicious backend that keeps you connected to IRC around the clock. But self-hosted means self-monitored: if the Mojolicious HTTP server stalls, the PostgreSQL database goes unreachable, or a WebSocket connection drops, your team is flying blind on IRC. Vigilmon adds the uptime monitoring, database health checks, and TLS certificate alerts that Convos doesn't ship with.

What You'll Set Up

  • HTTP uptime monitor for the Convos web server (port 3000)
  • WebSocket connectivity check via the Mojolicious endpoint
  • PostgreSQL database health heartbeat
  • File upload endpoint monitoring
  • TLS certificate expiry alerts

Prerequisites

  • Convos installed and running (standalone or Docker), accessible over HTTP/HTTPS
  • PostgreSQL running and reachable from the Convos host
  • A free Vigilmon account

Step 1: Monitor the Convos Web Server

Convos exposes its single-page app on port 3000 by default. The Mojolicious HTTP server handles both the static SPA assets and the API backend — if this process dies, everything stops.

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

If you run Convos behind an nginx reverse proxy (recommended), verify the proxy is passing WebSocket upgrades:

server {
    listen 443 ssl;
    server_name convos.yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:3000;
        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 2: Monitor the API Health Endpoint

Convos ships with a built-in health endpoint that reports server status:

  1. Add a Vigilmon monitor with Type HTTP / HTTPS.
  2. Set the URL to: https://convos.yourdomain.com/api
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 2 minutes.
  5. Click Save.

The API root returns a JSON response with Convos version and status. A non-200 here indicates the Mojolicious backend is broken even if the static assets are cached and the front page still loads.

Step 3: Add a WebSocket Health Check

Convos uses Mojolicious's real-time framework for live chat updates. The WebSocket endpoint at /events is what keeps browser clients in sync with the backend. A broken WebSocket means users see stale messages and can't send IRC messages.

Probe the connection upgrade path with a Vigilmon HTTP monitor:

  1. Add a monitor with Type HTTP / HTTPS.
  2. Set the URL to: https://convos.yourdomain.com/events
  3. Set Expected HTTP status to 101 (Switching Protocols) — or 200 if you want the non-upgrade response.
  4. Set Check interval to 3 minutes.
  5. Click Save.

If your monitoring tool can't send a proper WebSocket upgrade, check that the response contains the Upgrade: websocket header by checking the HTTP 101 status — that alone confirms the server is ready to upgrade connections.

Step 4: Monitor PostgreSQL Connectivity

Convos stores user accounts, IRC connection settings, and message history in PostgreSQL. A database outage means users cannot log in, connection configurations are lost, and message history becomes inaccessible.

Add a heartbeat monitor that pings only when PostgreSQL is reachable:

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

On your server, create a cron job:

# /etc/cron.d/convos-db-heartbeat
*/5 * * * * convos \
  pg_isready -h localhost -U convos -d convos -q && \
  curl -fsS --retry 3 https://vigilmon.online/ping/your-db-heartbeat-id > /dev/null 2>&1

pg_isready returns exit code 0 only when PostgreSQL accepts connections. If it fails, the curl is skipped and Vigilmon alerts on a missed heartbeat.

If you run Convos with Docker Compose, add the check as a health check in docker-compose.yml:

services:
  db:
    image: postgres:16
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U convos"]
      interval: 30s
      timeout: 10s
      retries: 3

Step 5: Monitor the File Upload Endpoint

Convos supports file sharing in IRC channels. If the upload service is broken, POST /api/user/:login/upload returns errors and users can't share files.

  1. Add a Vigilmon monitor with Type HTTP / HTTPS.
  2. Set the URL to: https://convos.yourdomain.com/api/user/your-test-user/upload
  3. Set Expected HTTP status to 401 (unauthenticated probe — a 401 means the endpoint is alive and enforcing auth).
  4. Set Check interval to 5 minutes.
  5. Click Save.

A 401 is the expected response for an unauthenticated probe to a protected endpoint — it proves the upload handler is registered and responding without actually uploading anything.

Step 6: Monitor Message History API

The history retrieval endpoint is what populates the chat backlog when users open a conversation. If it's broken, users see empty chat windows despite messages being stored in PostgreSQL.

  1. Add a Vigilmon monitor with Type HTTP / HTTPS.
  2. Set the URL to: https://convos.yourdomain.com/api/user/your-test-user/dialog/irc-freenode/messages
  3. Set Expected HTTP status to 401 (unauthenticated probe).
  4. Set Check interval to 5 minutes.
  5. Click Save.

Step 7: TLS Certificate Expiry

A Convos instance with an expired certificate breaks all connections immediately — browsers refuse to load the SPA and WebSocket connections fail.

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

If you use Let's Encrypt, verify the renewal timer:

systemctl status certbot.timer
# Check the next scheduled renewal
systemctl list-timers certbot.timer

Step 8: Configure Alerts

  1. Go to Settings → Alerts in Vigilmon.
  2. Add a Slack webhook, email, or webhook alert channel.
  3. Apply alerts to all Convos monitors.

Recommended alert thresholds:

| Monitor | Alert trigger | |---|---| | Web server | 1 consecutive failure | | API health | 2 consecutive failures | | WebSocket endpoint | 1 consecutive failure | | PostgreSQL heartbeat | 2 missed intervals | | TLS certificate | < 21 days remaining |

What to Watch

| Monitor | URL/Check | Interval | |---|---|---| | Web server | GET / → HTTP 200 | 1 minute | | API health | GET /api → HTTP 200 | 2 minutes | | WebSocket | GET /events → HTTP 101 | 3 minutes | | PostgreSQL | pg_isready heartbeat | 5 minutes | | File upload | POST /api/.../upload → 401 | 5 minutes | | Message history | GET /.../messages → 401 | 5 minutes | | TLS certificate | Expiry < 21 days | Passive |

Conclusion

Convos brings a modern web IRC experience to your self-hosted stack — and now you have the monitoring coverage to keep it running reliably. With Vigilmon watching the web server, PostgreSQL database, WebSocket endpoint, and TLS certificates, you'll know about failures within minutes rather than when users report empty chat windows.

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