Monitoring Monica CRM with Vigilmon

Monica is an open-source personal relationship manager — a CRM for your personal life. It tracks contacts, interactions, birthdays, reminders, and relationship notes, all hosted on your own server. It runs on PHP/Laravel at port 80 and depends on a database, a queue worker for emails, and a scheduler for reminders. When any of these break, you miss reminders, lose contact updates, and can't access your relationship data. Vigilmon gives you continuous monitoring for every layer of Monica so you're never caught off guard by a silent failure.

What You'll Set Up

• HTTP uptime monitoring for the Monica web interface
• Database connectivity health check
• Contact data API health probe
• Reminder scheduler heartbeat
• Email notification delivery monitoring
• Instant alerts for any failure

Prerequisites

• Monica CRM running on a server (default port 80 or 443, PHP/Laravel)
• A free Vigilmon account

Why Monica CRM Monitoring Matters

Monica stores personal relationship data you've invested real time building — contact histories, notes, journal entries, and scheduled reminders. Failures here aren't just technical annoyances:

• Web application down — you can't view contacts, add notes, or check upcoming birthdays
• Database unavailable — all contact data becomes inaccessible; Monica shows errors or blank pages
• Contact API broken — if you're using Monica's API for integrations or mobile clients, those connections silently fail
• Reminder scheduler stopped — scheduled birthday and follow-up reminders stop being processed; you miss important personal dates
• Email delivery broken — reminder emails and digest notifications stop being sent; the scheduler may run but the emails never arrive

Monica has no built-in alerting for these failures. You need external monitoring to catch them.

Step 1: Monitor the Monica Web Interface

Monica serves its UI on port 80 (or 443 with SSL). Add an HTTP uptime monitor:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter http://your-monica-domain.com (or https:// with SSL).
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

Monica's login page is a good proxy for full application health: it requires the web server, PHP-FPM, and application boot to all succeed. If any of those fail, the login page returns a non-200 or times out.

If you've set up a subdomain like monica.yourdomain.com, monitor that URL. If Monica is running on a non-standard port, include the port in the URL: http://your-server-ip:8080.

Step 2: Add a Database Health Endpoint

Monica uses MySQL or PostgreSQL for all contact and relationship data. A database failure takes down the entire app, but diagnosing it remotely is slow without a dedicated health endpoint.

Add a health check route to Monica's codebase. SSH into your Monica server and add to routes/api.php:

// routes/api.php
use Illuminate\Support\Facades\DB;

Route::get('/health', function () {
    try {
        DB::connection()->getPdo();
        return response()->json([
            'status' => 'ok',
            'database' => 'connected',
            'timestamp' => now()->toIso8601String(),
        ]);
    } catch (\Exception $e) {
        return response()->json([
            'status' => 'error',
            'database' => 'unreachable',
        ], 500);
    }
});

Clear the cache and verify:

php artisan route:cache
curl http://your-monica-domain.com/api/health
# {"status":"ok","database":"connected","timestamp":"..."}

Monitor it in Vigilmon:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-monica-domain.com/api/health
3. Expected status: 200
4. Expected body contains: "database":"connected"
5. Check interval: 2 minutes
6. Save.

If MySQL or PostgreSQL becomes unavailable, this endpoint returns 500 and you get an immediate alert.

Step 3: Monitor the Contact Data API Health

Monica exposes a REST API at /api for managing contacts, activities, reminders, and relationship data. If you use any integrations (Home Assistant, scripts, third-party apps), the API is a critical layer to monitor independently of the web UI.

Add a monitor for the API info endpoint, which returns Monica's version and API status without requiring authentication:

1. Click Add Monitor → HTTP / HTTPS.
2. URL: http://your-monica-domain.com/api
3. Expected status: 200
4. Check interval: 5 minutes
5. Save.

Verify it works:

curl http://your-monica-domain.com/api
# {"success":true,"data":{"version":"..."}}

For a deeper API health check, use a read-only authenticated probe. Create a long-lived API token in Monica (Settings → API) and add a monitor that authenticates:

1. URL: http://your-monica-domain.com/api/contacts
2. Custom header: Authorization: Bearer YOUR_MONICA_API_TOKEN
3. Expected status: 200
4. Check interval: 5 minutes

This confirms the full API stack — authentication, database reads, and serialization — is working end-to-end.

Step 4: Heartbeat for the Reminder Scheduler

Monica's reminder system relies on two things: the Laravel scheduler (which runs via php artisan schedule:run in a cron job) and the queue worker (which processes the actual notification dispatch). If either stops, reminders silently go unprocessed.

Add a scheduler heartbeat. Create a custom Artisan command:

// app/Console/Commands/VigilmonHeartbeat.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Http;

class VigilmonHeartbeat extends Command
{
    protected $signature = 'vigilmon:heartbeat';
    protected $description = 'Ping Vigilmon to confirm scheduler is running';

    public function handle(): int
    {
        $url = env('VIGILMON_SCHEDULER_HEARTBEAT_URL');
        if ($url) {
            Http::timeout(5)->get($url);
        }
        return Command::SUCCESS;
    }
}

Register it in the scheduler in app/Console/Kernel.php:

// app/Console/Kernel.php
protected function schedule(Schedule $schedule): void
{
    // Monica's existing scheduled tasks...

    // Add heartbeat
    $schedule->command('vigilmon:heartbeat')->everyFiveMinutes();
}

Add to your environment:

# .env
VIGILMON_SCHEDULER_HEARTBEAT_URL=https://vigilmon.online/heartbeat/YOUR_TOKEN

In Vigilmon:

1. Click Add Monitor → Cron Heartbeat.
2. Expected interval: 5 minutes.
3. Copy the heartbeat URL and set it in .env.
4. Save.

If the cron job stops firing or the scheduler process dies, Vigilmon alerts you within 5 minutes — before a birthday reminder gets missed.

Step 5: Monitor Email Notification Delivery

Monica sends reminder emails, birthday alerts, and follow-up notifications via Laravel's mail system (typically through an SMTP server or a mail API like Mailgun or Postmark). If the mail configuration breaks or the queue worker stops, emails go silent.

Add a queue worker heartbeat by pinging from a test job. Create a simple scheduled email probe:

// app/Console/Commands/EmailDeliveryCheck.php
namespace App\Console\Commands;

use Illuminate\Console\Command;
use Illuminate\Support\Facades\Mail;
use Illuminate\Support\Facades\Http;

class EmailDeliveryCheck extends Command
{
    protected $signature = 'vigilmon:email-check';
    protected $description = 'Test email delivery and ping heartbeat';

    public function handle(): int
    {
        try {
            // Send a test email to a monitored address
            Mail::raw('Monica email delivery check', function ($msg) {
                $msg->to(env('VIGILMON_CHECK_EMAIL'))
                    ->subject('Monica health check');
            });

            // Only ping if no exception was thrown
            $url = env('VIGILMON_EMAIL_HEARTBEAT_URL');
            if ($url) {
                Http::timeout(5)->get($url);
            }
        } catch (\Exception $e) {
            // No ping = Vigilmon alerts
            logger()->error('Monica email health check failed: ' . $e->getMessage());
        }

        return Command::SUCCESS;
    }
}

Schedule it hourly:

$schedule->command('vigilmon:email-check')->hourly();

In Vigilmon:

1. Click Add Monitor → Cron Heartbeat.
2. Expected interval: 60 minutes.
3. Copy the heartbeat URL and set it as VIGILMON_EMAIL_HEARTBEAT_URL.
4. Save.

If mail configuration breaks (SMTP credentials expired, provider rate-limiting, queue worker stopped), the heartbeat goes silent and you get alerted within an hour.

Step 6: Configure Alert Channels

1. In Vigilmon, go to Alert Channels → Add Channel.
2. Add Slack (paste your incoming webhook URL) or email.
3. On the web interface monitor, set Consecutive failures before alert to 2 to avoid alerts from brief PHP-FPM restarts.
4. On the scheduler and email heartbeats, set to 1 — a missed heartbeat here is always significant.
5. Enable alerts on all monitors.

Alert example:

🔴 DOWN: monica.yourdomain.com
Status: 502 Bad Gateway
Detected: 3 minutes ago

Heartbeat alert:

🔴 MISSED: Monica reminder scheduler heartbeat
Expected every: 5 minutes
Last ping received: 18 minutes ago

Recovery notification:

✅ RECOVERED: monica.yourdomain.com is back UP
Downtime: 11 minutes

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web interface | / | nginx down, PHP-FPM crash, app boot failure | | Database health | /api/health | MySQL/PostgreSQL connection failure | | Contact API | /api/contacts | API layer failure, auth broken | | Reminder scheduler | Cron heartbeat (5 min) | Cron stopped, scheduler process died | | Email delivery | Cron heartbeat (60 min) | SMTP broken, mail queue stopped |

Monica exists to help you stay close to the people who matter. Vigilmon makes sure the infrastructure behind it stays running reliably — so when a birthday comes around, the reminder lands in your inbox on time.

Get started free at vigilmon.online.