tutorial

Monitoring Kutt with Vigilmon

Kutt is a modern self-hosted URL shortener with a React frontend, Node.js backend, PostgreSQL, and Redis — here's how to monitor its health endpoint, database, Redis cache, and SSL certificates with Vigilmon.

Kutt is a modern self-hosted URL shortener with a React SPA frontend, a Node.js/Express backend, PostgreSQL for link storage, and Redis for rate limiting and caching. It supports custom domains per user, password-protected links, and detailed click analytics with browser, OS, and country breakdowns. Running Kutt gives you full ownership of your link analytics — but the multi-service architecture (Node.js + PostgreSQL + Redis) means there are multiple failure points to watch. Vigilmon monitors every layer, from the React frontend through the API health check down to the database and cache.

What You'll Set Up

  • HTTP monitor for the Kutt web UI (React SPA)
  • API health check using Kutt's built-in /api/v2/health endpoint
  • TCP probe for PostgreSQL database availability
  • TCP probe and heartbeat for Redis cache health
  • SSL certificate expiry alerts for your Kutt domain

Prerequisites

  • Kutt running via Docker Compose or directly on Node.js (typically port 3000, or reverse-proxied to port 80/443)
  • PostgreSQL accessible on port 5432
  • Redis accessible on port 6379
  • A free Vigilmon account

Step 1: Monitor the Kutt Web UI

The Kutt frontend is a React SPA served by the Node.js server. A 200 response with the keyword Kutt confirms the Node.js process is running and serving the application bundle.

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your Kutt URL: https://kutt.yourdomain.com/ (or http://localhost:3000/ for direct access).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Under Keyword check, enter Kutt to confirm the React app HTML is being served.
  7. Click Save.

This catches Node.js crashes, port binding failures, and cases where the process is running but serving an error page.

Step 2: Monitor the Kutt API Health Endpoint

Kutt ships with a dedicated health check endpoint at /api/v2/health that validates the full backend stack — including the PostgreSQL connection and Redis connection:

GET https://kutt.yourdomain.com/api/v2/health

Expected response:

{
  "status": "healthy"
}

This is the most important monitor in your Kutt setup because it tests all three tiers in a single call.

Add it in Vigilmon:

  1. Click Add Monitor → HTTP / HTTPS.
  2. URL: https://kutt.yourdomain.com/api/v2/health
  3. Expected status: 200.
  4. Keyword check: healthy — alerts if the response indicates a degraded state.
  5. Check interval: 1 minute.
  6. Click Save.

If PostgreSQL or Redis is unreachable, the health endpoint returns a non-healthy response or an HTTP error code, triggering an immediate alert.

Step 3: TCP Probe for PostgreSQL

The /api/v2/health endpoint validates PostgreSQL via Kutt's connection pool, but it won't catch cases where PostgreSQL is accepting TCP connections but Kutt's pool is exhausted. Add an independent TCP probe to confirm the database port is open:

  1. Click Add Monitor → TCP Port.
  2. Host: localhost (or the PostgreSQL host if running on a separate server).
  3. Port: 5432.
  4. Check interval: 2 minutes.
  5. Click Save.

A TCP probe failure at port 5432 means PostgreSQL is not accepting connections at all — a harder failure than a pool exhaustion that the health endpoint will also catch. Having both monitors gives you a clearer diagnosis when things go wrong.

Step 4: Monitor Redis Cache Health

Redis is critical to Kutt's rate limiting and link redirect caching. A failed Redis connection causes rate limiting to break and may degrade redirect performance under load, depending on your Kutt configuration.

TCP Probe for Redis

  1. Click Add Monitor → TCP Port.
  2. Host: localhost (or your Redis host).
  3. Port: 6379.
  4. Check interval: 2 minutes.
  5. Click Save.

Redis Health via the API Heartbeat

The TCP probe confirms Redis is accepting connections, but the /api/v2/health endpoint (Step 2) already validates Redis connectivity from Kutt's perspective. Keep both — the TCP probe gives you an independent signal if Kutt's health endpoint itself becomes unavailable.

For a deeper Redis health check using redis-cli:

redis-cli ping
# returns PONG if Redis is healthy

Add a cron heartbeat that validates Redis independently:

  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set Expected ping interval to 5 minutes.
  3. Copy the heartbeat URL.
  4. Add a cron job:
*/5 * * * * redis-cli -h localhost ping | grep -q PONG && curl -s https://vigilmon.online/heartbeat/redis-abc123

If redis-cli ping doesn't return PONG, the heartbeat ping is skipped and Vigilmon alerts after 5 minutes.

Step 5: SSL Certificate Alerts for Your Kutt Domain

Kutt supports custom domains per user — meaning users can add their own short link domains that resolve through your Kutt instance. Monitor the SSL certificate on your primary Kutt domain:

  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.

For a Kutt instance deployed with Docker Compose and a reverse proxy (nginx or Traefik), check certificate renewal:

# If using Certbot with nginx
certbot certificates

# If using Traefik with ACME
docker logs traefik 2>&1 | grep -i "certificate"

If you have users with custom domains enabled, remind them to monitor their own SSL certificates — Kutt resolves the short links but does not manage their SSL certificates.

Step 6: Configure Alert Channels and Thresholds

  1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook.
  2. Set thresholds per monitor:
    • Web UI (/): 2 consecutive failures — Node.js cold starts can occasionally cause single-probe timeouts.
    • API health (/api/v2/health): 1 failure — a failed health check means the full stack is degraded right now.
    • PostgreSQL TCP: 1 failure — database unavailability is always urgent.
    • Redis TCP: 2 failures — Redis briefly restarts during memory management; avoid false alerts.

Step 7: Verify with Docker Compose Logs

If you're running Kutt via Docker Compose, check service health with:

docker compose ps
# All services should show "Up" or "Up (healthy)"

docker compose logs kutt --tail=50
# Look for "Server is running" and no connection errors

docker compose logs postgres --tail=20
docker compose logs redis --tail=20

When Vigilmon alerts on the API health endpoint, check these logs first to identify whether the issue is in Kutt, PostgreSQL, or Redis.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | / keyword Kutt | Node.js crash, SPA not served | | API health | /api/v2/health | Full stack degraded (DB + Redis) | | PostgreSQL TCP | Port 5432 | Database not accepting connections | | Redis TCP | Port 6379 | Redis not accepting connections | | Redis heartbeat | redis-cli ping | Silent Redis failure | | SSL certificate | Your Kutt domain | Certificate expiry |

Kutt's multi-service architecture delivers powerful analytics and custom domain support, but each service is a potential failure point. With Vigilmon covering the Node.js layer, the health endpoint, PostgreSQL, Redis, and SSL certificates, you have full visibility across the stack — and you'll know exactly which component failed before your users report broken links.

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