Monitoring Peppermint Helpdesk with Vigilmon

Peppermint is an open-source helpdesk and ticketing system built on Node.js and Next.js, with PostgreSQL for storage and an IMAP poller to convert incoming emails into support tickets. For small teams running their own support stack, Peppermint replaces SaaS tools like Zendesk — but self-hosting means you own the reliability too. A crashed IMAP poller, a full PostgreSQL disk, or a broken SMTP relay can silently swallow customer emails for hours. Vigilmon monitors every layer — the web server, database, email ingestion, outbound delivery, and background jobs — so you catch failures before your customers do.

What You'll Set Up

• HTTP uptime monitor for the Peppermint web app (port 3000)
• PostgreSQL connectivity check via the API
• Email ingestion health with a cron heartbeat
• SMTP outbound delivery validation
• Client portal endpoint check
• SSL certificate expiry alerts

Prerequisites

• Peppermint running on a server or Docker (Node.js/Next.js, port 3000)
• PostgreSQL database accessible by the Peppermint container
• A free Vigilmon account

Step 1: Monitor the Peppermint Web Server

Peppermint's Next.js server handles the management dashboard and the ticket API on port 3000. Add an HTTP monitor:

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

If you've placed Peppermint behind nginx with a subdomain, monitor the proxied URL so the check covers both the reverse proxy and the Node.js process.

Step 2: Check the Ticket API Endpoint

Peppermint's REST API validates that the Node.js backend and PostgreSQL are both responding. Add a monitor for the ticket creation endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-server:3000/api/v1/ticket/all
3. Expected HTTP status: 401 — unauthenticated requests return 401, which confirms the API is responding and the database connection is active.
4. Check interval: 2 minutes.
5. Click Save.

A 500 or connection timeout here indicates a database problem or application crash, even while the homepage might still be cached and load from the CDN or proxy.

Step 3: Monitor PostgreSQL via Response Time

Peppermint stores all tickets, users, clients, and email threads in PostgreSQL. Slow queries cause degraded performance across the entire helpdesk. Monitor API response time as a proxy for database health:

1. Open the API monitor created in Step 2.
2. Set Maximum response time to 2000 ms.
3. Click Save.

For direct database monitoring, add a TCP port monitor for PostgreSQL:

1. Click Add Monitor → TCP Port.
2. Host: your PostgreSQL server IP or hostname.
3. Port: 5432.
4. Check interval: 2 minutes.
5. Click Save.

Step 4: Heartbeat for Email Ingestion (IMAP Poller)

Peppermint polls a configured IMAP mailbox on a regular interval to turn incoming emails into tickets. If the IMAP poller crashes or loses connectivity to the mail server, emails pile up silently — customers never get a ticket acknowledgment and agents never see the request.

Create a Vigilmon cron heartbeat and wire it into a health check script on the Peppermint host:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set Expected interval to your IMAP polling interval (commonly 5 minutes for Peppermint).
3. Copy the heartbeat URL.
4. On your Peppermint host, add a cron job that checks the IMAP connectivity and pings Vigilmon on success:

#!/bin/bash
# /usr/local/bin/peppermint-email-health.sh
# Test IMAP connectivity to the configured mailbox server
if nc -z -w5 mail.yourdomain.com 993 2>/dev/null; then
  curl -s https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_ID
fi

Schedule it in cron:

*/5 * * * * /usr/local/bin/peppermint-email-health.sh

If the IMAP server is unreachable for a full polling cycle, Vigilmon fires an alert.

Step 5: Validate SMTP Outbound Delivery

Peppermint sends reply emails and ticket notifications via SMTP. A broken SMTP relay means agents can reply to tickets in the dashboard but customers never receive the responses. Add a TCP monitor for your SMTP server:

1. Click Add Monitor → TCP Port.
2. Host: your SMTP server hostname (e.g., smtp.yourdomain.com).
3. Port: 587 (STARTTLS submission) or 465 (SMTPS).
4. Check interval: 5 minutes.
5. Click Save.

For end-to-end SMTP validation, complement the TCP check with a transactional email service health check (Mailgun, Postmark, or SendGrid status page monitor) using Vigilmon's HTTP monitor pointing to their status API.

Step 6: Monitor the Client Portal

Peppermint exposes a client-facing portal at /portal where customers can view their ticket status without logging into the main admin interface. Add a dedicated monitor for this endpoint:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-server:3000/portal
3. Expected HTTP status: 200.
4. Check interval: 5 minutes.
5. Click Save.

The portal is a separate Next.js route — it can fail independently of the admin dashboard if a page component throws an unhandled error.

Step 7: Background Job Queue Health

Peppermint runs background jobs for email polling and outbound notifications. These run as part of the Node.js process, so a hung event loop stalls them silently. Add a response-time monitor on the main API to detect this:

1. Open the API monitor from Step 2.
2. Enable Alert if response time exceeds 3000 ms.
3. Click Save.

A slow or hung API response indicates the Node.js event loop is blocked — often a symptom of a stuck background job or a long-running database query.

Step 8: File Attachment Storage Accessibility

Ticket attachments are stored on disk (or a configured object store). A full disk or misconfigured storage path causes attachment uploads to fail silently. Add a monitor for the static file serving path:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-server:3000/api/v1/data/uploads/ (or your configured attachment base URL).
3. Expected HTTP status: 200 or 403 — either confirms the storage path is reachable.
4. Check interval: 10 minutes.
5. Click Save.

Step 9: SSL Certificate Alerts

If Peppermint is exposed over HTTPS via a reverse proxy, add a certificate expiry monitor:

1. Open the HTTPS monitor for your Peppermint domain.
2. Enable Monitor SSL certificate.
3. Set Alert when certificate expires in less than 21 days.
4. Click Save.

Step 10: Configure Alert Channels

1. Go to Alert Channels and add Slack, email, or a webhook connected to your team's communication tool.
2. Set Consecutive failures before alert to 2 on HTTP monitors — Next.js can take several seconds to cold-start after a restart.
3. Add a Maintenance window during planned Peppermint upgrades to suppress false alerts.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web server HTTP | :3000/ | App crash, Node.js down | | Ticket API | :3000/api/v1/ticket/all | DB failure, backend crash | | PostgreSQL TCP | :5432 | Database unreachable | | IMAP heartbeat | Heartbeat URL | Email poller down, mail server unreachable | | SMTP TCP | :587 / :465 | Outbound email broken | | Client portal | :3000/portal | Portal page failure | | API response time | :3000/api/ | Event loop blocked, slow queries | | SSL certificate | HTTPS domain | TLS cert expiry |

Peppermint makes self-hosted helpdesk practical for small teams — but the email ingestion pipeline and background jobs are the heart of it. With Vigilmon watching every layer, you'll catch a broken IMAP poll or a crashed SMTP relay before a customer reports that their ticket went unanswered.