Monitoring Zammad with Vigilmon

Zammad is a modern open-source ticket system built with Ruby on Rails, real-time WebSocket updates, and Elasticsearch-powered full-text search. It handles customer support, internal IT tickets, and shared inboxes for organizations that want full control of their support data. But its multi-component architecture — Rails app, Elasticsearch, PostgreSQL, and background job workers — means there are multiple failure points to watch. Vigilmon covers all of them: the web UI, the built-in health check endpoint, Elasticsearch connectivity, SSL certificates, and the background jobs that handle email fetching and search indexing.

What You'll Set Up

• HTTP monitor for the Zammad web UI availability
• HTTP monitor for the /api/v1/monitoring/health_check JSON health endpoint
• TCP port monitor for Elasticsearch connectivity (port 9200)
• SSL certificate expiry alerts for HTTPS Zammad setups
• Cron heartbeat for Zammad background jobs (email fetching, Elasticsearch indexing)

Prerequisites

• Zammad 6.x installed (package or Docker) and accessible over HTTP/HTTPS
• Elasticsearch running and indexed
• A free Vigilmon account

Step 1: Monitor the Zammad Web UI

The Zammad frontend is the primary user-facing surface. Monitoring its availability ensures that agents can log in, view tickets, and respond to customers.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your Zammad URL: https://support.yourdomain.com/.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword check, enter Zammad to confirm the application loads correctly, not just the web server.
7. Click Save.

The keyword check catches a common failure mode: the web server (nginx) returns 200 with an error page when the Rails Puma/Unicorn process has crashed.

Step 2: Monitor the Zammad Health Check Endpoint

Zammad includes a built-in monitoring endpoint at /api/v1/monitoring/health_check that reports the internal health of the application. This is the most direct way to know whether Zammad considers itself functional.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: https://support.yourdomain.com/api/v1/monitoring/health_check.
3. Set Check interval to 2 minutes.
4. Set Expected HTTP status to 200.
5. Under Keyword check, enter "healthy":true to validate the JSON response content.
6. Click Save.

The health check endpoint returns JSON like:

{"healthy":true,"message":"success"}

When Elasticsearch is unreachable or background jobs are failing, this endpoint returns "healthy":false with a message describing the issue. Vigilmon's keyword check will catch the change.

To verify the endpoint manually:

curl -s https://support.yourdomain.com/api/v1/monitoring/health_check | python3 -m json.tool

Step 3: Monitor Elasticsearch Connectivity

Zammad depends on Elasticsearch for ticket full-text search. When Elasticsearch goes down, search stops working and new ticket indexing fails — but the UI may still appear functional. Monitor the Elasticsearch TCP port directly.

1. Click Add Monitor → TCP Port.
2. Enter the Elasticsearch host (e.g. elasticsearch.internal or localhost).
3. Set Port to 9200.
4. Set Check interval to 1 minute.
5. Click Save.

For a more thorough check, monitor the Elasticsearch HTTP API:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter: http://elasticsearch.internal:9200/_cluster/health.
3. Set Expected HTTP status to 200.
4. Under Keyword check, enter "status":"green" (or "yellow" if you run a single-node cluster).
5. Click Save.

A single-node Elasticsearch cluster will always report yellow status (no replica shards) — this is expected for development setups. Use "status":"red" as an alert condition if you want to avoid false alarms on single-node installs by instead checking that the status is NOT red.

Step 4: SSL Certificate Alerts for HTTPS Zammad Setups

Zammad installations are typically proxied through nginx with a Let's Encrypt certificate. Certificate expiry causes browsers to block access entirely — agents can't log in and customers can't submit tickets.

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

For multi-domain Zammad setups (e.g. a custom help.yourdomain.com in addition to the main domain), add a separate SSL monitor for each domain:

# Check certificate expiry manually
echo | openssl s_client -connect support.yourdomain.com:443 2>/dev/null | openssl x509 -noout -enddate

Step 5: Heartbeat Monitoring for Zammad Background Jobs

Zammad background workers handle email fetching, sending, Elasticsearch indexing, and scheduled notifications. These jobs run as separate processes (bundle exec rake jobs:work or via systemd units). If they crash, email stops flowing and search indexes fall behind — silently.

Set up a Vigilmon heartbeat to detect stopped background workers:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 15 minutes.
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Create a cron job that checks whether the Zammad worker process is alive and pings Vigilmon:

# /etc/cron.d/zammad-heartbeat
*/15 * * * * root /usr/bin/systemctl is-active --quiet zammad-worker.service && curl -s https://vigilmon.online/heartbeat/abc123

For Docker-based Zammad installations, check the worker container:

*/15 * * * * root docker exec zammad-railsserver bundle exec rails r "puts Delayed::Job.count" > /dev/null 2>&1 && curl -s https://vigilmon.online/heartbeat/abc123

Alternatively, send the heartbeat from within the worker after each successful job batch if you have customized the Zammad job processing.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and connect Slack, email, or a webhook to your support team's notification channel.
2. Set Consecutive failures before alert to 2 on the web UI monitor — transient Rails restarts during deployments take a few seconds.
3. Set Consecutive failures before alert to 1 on the health check endpoint — a failed health check is an immediate signal of internal problems.
4. Route Elasticsearch and background job alerts to your infrastructure team separately from web UI alerts.

For Zammad upgrades, pause monitoring to avoid false alerts during restart:

curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "zammad-webui", "duration_minutes": 15}'

systemctl restart zammad

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP — web UI | https://support.yourdomain.com/ | Rails crash, nginx misconfiguration | | HTTP — health check | /api/v1/monitoring/health_check | Internal app failure, unhealthy state | | TCP port | Elasticsearch :9200 | Search engine down | | SSL certificate | Zammad domain | Certificate expiry, Let's Encrypt failure | | Cron heartbeat | Heartbeat URL | Background worker crash, email fetch stopped |

Zammad's strength is its real-time, multi-channel support experience — but that experience depends on a healthy stack of Rails, Elasticsearch, and background workers all running together. Vigilmon gives you a single dashboard to confirm every layer is operational, and alerts you the moment any component goes silent.