Monitoring FreeScout with Vigilmon

FreeScout is a lightweight, self-hosted PHP help desk built on Laravel — the open-source alternative to Zendesk and HelpScout. It gives support teams a shared inbox, conversation threads, and email integration without a SaaS subscription. But as a self-hosted application, FreeScout's availability is entirely your responsibility: if the cron scheduler stops, emails stop arriving and auto-replies stop sending — silently. Vigilmon monitors the full FreeScout stack: the web UI, the API endpoint, mailbox conversation health, SSL certificates, and the cron job that keeps email flowing.

What You'll Set Up

• HTTP monitor for the FreeScout web UI (login page)
• HTTP monitor for the /api endpoint availability
• HTTP keyword monitor for conversation/mailbox API health
• SSL certificate expiry alerts for HTTPS FreeScout setups
• Cron heartbeat for the FreeScout cron scheduler (automated email polling and sending)

Prerequisites

• FreeScout installed on a PHP/Apache or nginx stack (or Docker)
• Cron job configured for FreeScout's Laravel scheduler
• A free Vigilmon account

Step 1: Monitor the FreeScout Login Page

The FreeScout login page confirms the PHP application, web server, and database connection are all healthy.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your FreeScout URL: https://help.yourdomain.com/.
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword check, enter FreeScout to confirm the application renders correctly (not a Laravel error page or blank screen from a misconfigured .env).
7. Click Save.

A keyword check is particularly useful for FreeScout because Laravel's error handling can return HTTP 200 with a Whoops error page when the database or configuration is broken — a status-code-only check would miss this.

Step 2: Monitor the FreeScout API Endpoint

FreeScout's REST API is available at /api (when the FreeScout API module is installed). Monitoring its availability confirms the API layer is operational for integrations and mobile clients.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: https://help.yourdomain.com/api.
3. Set Check interval to 5 minutes.
4. Set Expected HTTP status to 200.
5. Click Save.

If your FreeScout instance doesn't have the API module installed, the /api endpoint returns a 404. In that case, skip this monitor or use a different API path provided by any modules you have installed.

To verify the API is reachable manually:

curl -I https://help.yourdomain.com/api

A 200 OK with a JSON response body confirms the API is online.

Step 3: Monitor Mailbox Health via HTTP Keyword Check

FreeScout's mailboxes are central to its function — a misconfigured or disconnected mailbox silently stops delivering emails to conversations. Use a Vigilmon keyword check against the API conversations endpoint to confirm the API can return conversation data.

1. Click Add Monitor → HTTP / HTTPS.
2. Enter: https://help.yourdomain.com/api/conversations?page=1 (requires API authentication — use an API key from FreeScout's API module settings).
3. Set Check interval to 10 minutes.
4. Set Expected HTTP status to 200.
5. Under HTTP Headers, add:

   Authorization: Bearer YOUR_FREESCOUT_API_KEY
   

6. Under Keyword check, enter "_embedded" to confirm the API response has the expected conversation data structure.
7. Click Save.

This check confirms the API, database connectivity, and conversation retrieval are all working end-to-end. If the database goes down, this check fails even if the login page still loads from Laravel's session cache.

Step 4: SSL Certificate Alerts for HTTPS FreeScout Setups

FreeScout is typically served over HTTPS via nginx or Apache with Let's Encrypt. An expired certificate locks out all users and breaks email webhook callbacks from delivery providers.

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.

To check your current certificate status:

echo | openssl s_client -connect help.yourdomain.com:443 2>/dev/null | openssl x509 -noout -dates

If you run FreeScout behind a load balancer or CDN, also add an SSL monitor for the origin certificate separately to catch upstream expiry before it propagates.

Step 5: Heartbeat Monitoring for the FreeScout Cron Scheduler

FreeScout's email polling, auto-replies, and conversation auto-closing all depend on Laravel's cron scheduler running every minute. A typical FreeScout cron entry looks like:

* * * * * www-data php /var/www/freescout/artisan schedule:run >> /dev/null 2>&1

If this cron job stops — due to a misconfigured crontab, permission error, or system reboot without a restored cron daemon — emails stop flowing entirely with no error visible in the FreeScout UI.

Set up a Vigilmon heartbeat to detect missed runs:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 5 minutes.
3. Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).
4. Update your crontab entry to ping Vigilmon after each successful scheduler run:

* * * * * www-data php /var/www/freescout/artisan schedule:run >> /var/log/freescout-cron.log 2>&1 && curl -s https://vigilmon.online/heartbeat/abc123

The && ensures the heartbeat ping only fires when artisan schedule:run exits successfully. Any PHP error or permission failure prevents the ping and triggers a Vigilmon alert after 5 minutes.

For Docker-based FreeScout deployments:

* * * * * root docker exec freescout php artisan schedule:run >> /var/log/freescout-cron.log 2>&1 && curl -s https://vigilmon.online/heartbeat/abc123

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and connect email or Slack to your support team's channel.
2. Set Consecutive failures before alert to 2 on the web UI monitor — a single slow response during mail processing spikes shouldn't page the team.
3. Set Consecutive failures before alert to 1 on the cron heartbeat — a missed cron run means email has already stopped for several minutes.
4. Consider routing the mailbox API health check alert to the same channel as the heartbeat: if both fire together, the Laravel app and scheduler are likely both down.

For FreeScout updates, suppress monitoring alerts during the maintenance window:

# Pause monitoring before update
curl -X POST https://vigilmon.online/api/maintenance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"monitor_id": "freescout-webui", "duration_minutes": 10}'

# Run the FreeScout update
cd /var/www/freescout
git pull
composer install --no-dev
php artisan freescout:fetch-emails
php artisan migrate --force

# Maintenance window expires automatically after 10 minutes

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP — login page | https://help.yourdomain.com/ | App crash, PHP error, DB connection failure | | HTTP — API endpoint | /api | API module down | | HTTP — mailbox API | /api/conversations | Conversation retrieval failure, DB down | | SSL certificate | FreeScout domain | Certificate expiry, Let's Encrypt renewal failure | | Cron heartbeat | Heartbeat URL | Missed cron run, email polling stopped |

FreeScout's simplicity is its strength — but that simplicity means there's no built-in health dashboard to tell you when the scheduler has stalled or the database has dropped. Vigilmon fills that gap, giving you real-time alerts across every layer so support emails keep flowing and your team stays responsive even when something breaks at 3 AM.