Monitoring Huginn with Vigilmon

Huginn is a mature open-source autonomous agent system built on Ruby on Rails — a self-hosted IFTTT/Zapier with real scripting power. Agents monitor RSS feeds, email, weather APIs, social streams, and arbitrary HTTP endpoints, then chain together automated actions: notifications, webhooks, data transforms, and service integrations. When Huginn's background job worker stops, agents queue up silently — no notifications fire, no webhooks trigger — without any visible error. Vigilmon catches it: web UI availability, login page health, TCP port monitoring, SSL certificate expiry, and a self-monitoring agent heartbeat loop that Huginn itself creates.

What You'll Set Up

• HTTP uptime monitor for the Huginn web UI (port 3000)
• Login page availability check (verifies Rails application + database)
• TCP port 3000 monitoring (Puma web server health)
• SSL certificate expiry alerts for Nginx-proxied deployments
• Huginn agent heartbeat: a Huginn agent that pings Vigilmon to create a self-monitoring loop

Prerequisites

• Huginn running via Docker or bare metal (default port 3000, Puma server)
• HTTPS proxy configured (Nginx) for production deployments
• A free Vigilmon account

Step 1: Monitor the Huginn Web UI

The Huginn web interface is the first indicator that the Rails application is alive. Add an HTTP monitor that catches Puma crashes, container failures, or nginx proxy issues:

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

Huginn redirects unauthenticated root requests to the login page or the dashboard depending on your configuration. Either way, a 200 response confirms the Rails server is up and routing requests.

Step 2: Monitor the /users/sign_in Login Page

The /users/sign_in page is a reliable deep health check for Huginn because it exercises the full Rails stack: routing, controller, ActiveRecord database query (to check for existing users), and view rendering. If any layer fails, the page returns an error:

1. Add a new HTTP / HTTPS monitor in Vigilmon.
2. Set the URL to https://huginn.yourdomain.com/users/sign_in.
3. Set Check interval to 1 minute.
4. Set Expected HTTP status to 200.
5. Under Response body contains, enter "Sign in" to assert the login form is actually rendered.
6. Click Save.

You can verify this manually:

curl -s https://huginn.yourdomain.com/users/sign_in | grep "Sign in"

This check is particularly valuable because it validates database connectivity — Huginn queries the database to render the login page, so a 200 response here means PostgreSQL (or MySQL) is connected and responding. A database failure surfaces immediately as a 500 error on this endpoint.

Step 3: TCP Port 3000 Monitoring

Huginn runs on Puma, a Ruby web server that listens on port 3000 (typically proxied via Nginx to port 80/443). A TCP port check catches port-binding failures that HTTP checks behind a proxy would miss entirely:

1. In Vigilmon, click Add Monitor → TCP Port.
2. Set the host to your Huginn server hostname or IP.
3. Set the port to 3000 (the Puma port, not the Nginx port).
4. Click Save.

This is especially useful for Docker deployments where the port mapping can silently fail:

# docker-compose.yml excerpt
services:
  huginn:
    image: ghcr.io/huginn/huginn
    ports:
      - "3000:3000"   # If this binding fails, HTTP checks via nginx still pass
    environment:
      DATABASE_URL: postgres://huginn:${DB_PASSWORD}@db/huginn

The TCP check bypasses Nginx and probes Puma directly — if the container loses its port binding, you'll know immediately.

Step 4: SSL Certificate Alerts

Huginn is typically deployed behind Nginx for TLS termination. A lapsed certificate doesn't just break browser access — it also breaks any external services that POST webhooks to your Huginn agents (services sending event payloads to Huginn's webhook receiver will start receiving TLS errors).

Enable SSL monitoring on your existing Huginn HTTP monitor:

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

For Nginx-managed certificates, check your renewal setup:

# Verify Certbot auto-renewal will work
certbot renew --dry-run

# List certificate expiry dates
certbot certificates

# Your Nginx config should have the certificate paths:
# ssl_certificate /etc/letsencrypt/live/huginn.yourdomain.com/fullchain.pem;
# ssl_certificate_key /etc/letsencrypt/live/huginn.yourdomain.com/privkey.pem;

If auto-renewal fails and you catch it with the Vigilmon 21-day alert, you have time to renew manually:

certbot renew --force-renewal -d huginn.yourdomain.com
nginx -s reload

Step 5: Huginn Agent Heartbeat — The Self-Monitoring Loop

The most critical Huginn failure mode is the background job worker stopping. Huginn agents run as Delayed::Job background jobs — if the worker process dies, agents stop executing entirely. The web UI continues to show "scheduled" agents, events accumulate in the queue, and nothing fires. Hours can pass before anyone notices.

Vigilmon's heartbeat monitor turns this into an immediate alert. The elegance of the Huginn approach: you configure a Huginn agent to be the thing that pings Vigilmon. If Huginn's worker is running, the ping arrives. If the worker dies, the ping stops.

Step 5a: Create a Vigilmon heartbeat monitor

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 60 minutes (or match the frequency of your most important agent).
3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID.

Step 5b: Create a Huginn PostAgent that pings Vigilmon

In the Huginn web UI:

1. Click Agents → New Agent.
2. Select Post Agent as the type.
3. Configure it:

{
  "post_url": "https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID",
  "expected_receive_period_in_days": "1",
  "method": "get",
  "no_merge": "false",
  "output_mode": "clean"
}

4. Set Schedule to Every 1 hour.
5. Set the agent to run on schedule (not on event receive).
6. Save the agent.

Step 5c: Create a trigger agent to drive it on schedule

Huginn's PostAgent runs on events by default. To make it run on a schedule, pair it with a TriggerAgent or use a SchedulerAgent (if installed):

Alternatively, use Huginn's built-in scheduler by setting the PostAgent's Keep events for and Expected update period correctly, and rely on the schedule field:

The PostAgent with a schedule set will fire without needing incoming events — it generates its own empty event on each schedule tick and POSTs to the heartbeat URL.

The self-monitoring loop in action:

Every 60 minutes:
  Huginn scheduler → fires PostAgent → GET https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID
  
If worker stops:
  No ping for 60+ minutes → Vigilmon alert fires → you investigate

Step 5d: Add a scheduled test agent for deeper verification

For even stronger assurance, create a secondary Huginn agent that does something meaningful — like checking an HTTP endpoint — and have it trigger the PostAgent on success. This confirms not just that the worker is running, but that agents can successfully complete network requests:

1. Create a WebsiteAgent that checks https://example.com every hour.
2. In its options, set it to propagate an event on success.
3. Connect the PostAgent to receive events from the WebsiteAgent.
4. The PostAgent pings Vigilmon only after the WebsiteAgent successfully completes.

Now the heartbeat ping proves: the worker is running AND agents can make outbound network requests.

Step 6: 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 on the web UI monitor — a Docker container restart can cause one probe to fail transiently.
3. Suppress alerts during Huginn upgrades with a maintenance window:

# Pause monitors during a Huginn container upgrade
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "abc123", "duration_minutes": 10}'

# Pull and restart the Huginn container
docker compose pull huginn && docker compose up -d huginn

# Maintenance window expires automatically

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://huginn.domain.com | Puma crash, container failure, nginx down | | Login page | /users/sign_in | Database disconnection, Rails error | | TCP port | :3000 | Port binding failure (bypasses nginx proxy) | | SSL certificate | Main domain | Let's Encrypt renewal failure, webhook TLS break | | Agent heartbeat | Vigilmon heartbeat URL | Delayed::Job worker stopped, agents not running |

Huginn's self-hosted agent model gives you IFTTT-level automation with full data ownership — but it also means you own the reliability. With Vigilmon watching the web UI, login page health, TCP port, SSL certificate, and a Huginn agent pinging back every hour, you'll catch worker failures in minutes rather than discovering them when your most important automation silently stopped firing days ago.