How to Monitor Your Firefly III Instance with Vigilmon

Firefly III is a self-hosted personal finance manager that tracks your transactions, budgets, and net worth. When you run it yourself, you control your financial data — but you also own the uptime. A down Firefly III means you can't log transactions, your automatic import rules stop running, and your financial overview goes dark. Vigilmon keeps your Firefly III instance under continuous surveillance so you're the first to know when something breaks.

What You'll Monitor

• The /api/v1/about health endpoint (API availability check)
• The Firefly III web UI (main dashboard interface)
• Cron job heartbeat (recurring import and rule execution)
• SSL certificate expiry

Prerequisites

• A self-hosted Firefly III instance (Docker or bare-metal PHP)
• A free Vigilmon account
• Your Firefly III URL (e.g. https://money.yourdomain.com)

Why Monitor Firefly III?

Firefly III is a PHP/Laravel application backed by a MySQL or PostgreSQL database. It has several independent failure modes:

• The PHP-FPM pool exhausts workers and requests start timing out
• The database disk fills up and new transactions fail silently
• The cron job that runs automatic imports and rules stops firing
• A Laravel queue worker dies and background jobs queue up indefinitely

External monitoring from Vigilmon checks Firefly III the way you would — by hitting real endpoints from outside your server — and catches failures before you notice them during your next budget review.

Step 1: Monitor the About/Health Endpoint

Firefly III's REST API includes an /api/v1/about endpoint that returns version and status information when the application is running correctly.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: https://money.yourdomain.com/api/v1/about
4. Set Check interval to 1 minute.
5. Set Expected status code to 200.
6. Under Request headers, add Accept: application/vnd.api+json — the Firefly III API requires this header.
7. Under Expected body contains, enter "version" — a successful response always includes the application version.
8. Name it Firefly III – API health and click Save.

A healthy response looks like:

{
  "data": {
    "attributes": {
      "version": "6.1.0",
      "api_version": "2.0.0",
      "php_version": "8.2.10",
      "os": "Linux",
      "driver": "mysql"
    }
  }
}

If the Laravel application or database is unreachable, this returns 500 or times out.

Step 2: Monitor the Web UI

The web dashboard is what you use every day to review transactions and budgets. A broken UI means you're locked out even if the API is running.

1. Click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter: https://money.yourdomain.com
4. Set Expected status code to 200.
5. Under Expected body contains, enter Firefly — the login and dashboard pages include this in the page title and body.
6. Name it Firefly III – Web UI and save.

Step 3: Monitor Cron Jobs with a Heartbeat

Firefly III relies on cron jobs to run automatic transaction imports, apply recurring transactions, and execute automation rules. If your cron job stops running — due to a misconfigured crontab, a restart that wipes /etc/cron.d, or a container restart with no persistent cron — these tasks silently stop without any error.

Set up a Vigilmon heartbeat to monitor cron execution:

1. In Vigilmon, go to Heartbeat Monitors → Add Heartbeat.

2. Name it Firefly III – Cron Job.

3. Set Expected interval to 1 day and Grace period to 2 hours.

4. Copy the generated heartbeat URL (e.g. https://vigilmon.online/heartbeat/YOUR_TOKEN).

5. Add the ping to your Firefly III cron entry. The official Firefly III cron command is:

# /etc/cron.d/firefly
0 3 * * * www-data /usr/bin/php /var/www/firefly-iii/artisan firefly-iii:cron && curl -s https://vigilmon.online/heartbeat/YOUR_TOKEN

If you run Firefly III in Docker, add the heartbeat ping to your Docker cron configuration:

0 3 * * * curl -s "http://localhost/api/v1/cron/YOUR_CRON_TOKEN" && curl -s https://vigilmon.online/heartbeat/YOUR_TOKEN

Now if the cron job stops firing for more than 26 hours (24h interval + 2h grace), Vigilmon sends an alert.

Step 4: SSL Certificate Alerts

Firefly III stores sensitive financial data, so HTTPS is non-negotiable. An expired certificate locks you out of your own dashboard and breaks any mobile apps or scripts that connect to the API.

1. Open the Web UI monitor settings.
2. Under SSL Certificate, enable Alert before expiry.
3. Set warnings at 30 days and 7 days before expiry.
4. Save, and apply the same setting to the API health monitor.

Step 5: Configure Alert Channels

1. In Vigilmon, go to Alert Channels → Add Channel.
2. Add your preferred channel — Email, Slack, or a webhook for your notification service.
3. For Slack:

{
  "text": "🚨 *{{monitor_name}}* is {{status}}!\nURL: {{url}}\nTime: {{timestamp}}"
}

4. Attach this channel to all three monitors (API health, Web UI, Cron heartbeat).

Step 6: Verify the Alert Pipeline

1. Temporarily change the Expected body contains on the API health monitor to a string that won't match (e.g. vigilmon-test).
2. Wait one check cycle — you should receive an alert within 2 minutes.
3. Restore the setting and confirm the recovery notification arrives.
4. For the cron heartbeat test: skip one scheduled ping by commenting out the cron temporarily, then verify Vigilmon alerts after the grace period.

Going Further

• Queue worker monitoring: Firefly III uses Laravel queues for some background jobs. If you run artisan queue:work separately, add a second heartbeat for the queue worker process.
• Database disk alert: Add a server-level alert to your host for disk usage — a full disk is the most common cause of silent Firefly III failures.
• Status page: Share a Vigilmon status page with your household or anyone else who shares access to the Firefly III instance.

Your Firefly III installation is now fully monitored: API health, web dashboard, cron job execution, and SSL — giving you confidence that your financial data is always accessible when you need it.