Pixelfed Monitoring with Vigilmon: Web UI, API Health, Horizon Queue & Federation Checks

Your Pixelfed instance was running fine — photos were uploading, the feed was loading, and users were logging in without issue. Then someone mentioned their media hadn't appeared on another Pixelfed server in two days. The Horizon queue had silently backed up with 3,000 unprocessed federation jobs. The web UI never showed any sign of trouble.

Pixelfed is a self-hosted federated photo-sharing platform and ActivityPub-compatible Instagram alternative. A healthy Pixelfed instance depends on the Laravel web process, the Horizon queue worker (which handles federation and media processing), PostgreSQL, Redis, and your web server all staying healthy together. When any layer quietly fails, users rarely notice until federation breaks or uploads stop processing. Vigilmon gives you the external monitoring layer to catch these failures before they compound.

This tutorial walks through monitoring Pixelfed end-to-end with Vigilmon.

What You'll Build

• A Vigilmon HTTP monitor on the Pixelfed web UI
• An API health check using Pixelfed's well-known endpoint
• A media upload service availability check
• A Vigilmon heartbeat monitor for Horizon queue worker health
• A federation endpoint check
• SSL certificate expiry alerts

Prerequisites

• A running Pixelfed instance (v0.11.x or later recommended)
• A free account at vigilmon.online

Step 1: Monitor the Pixelfed Web UI

The Pixelfed homepage is the entry point for all users. A 200 response from the root URL confirms that Nginx, the PHP-FPM process, Laravel, and the database connection are all operational.

Test it:

curl -I https://pixelfed.yourdomain.com/

You should see 200 OK with a Content-Type: text/html response.

Set up the Vigilmon monitor:

1. Log in to Vigilmon and click New Monitor → HTTP.
2. Set URL to https://pixelfed.yourdomain.com/.
3. Set Check interval to 60 seconds.
4. Set Expected status code to 200.
5. Under Advanced → Keyword check, add keyword present: Pixelfed.
6. Save the monitor.

Step 2: Monitor the API Health Endpoint

Pixelfed exposes a Mastodon-compatible API at /api/v1/instance. This endpoint returns instance metadata and confirms that Laravel can reach the database. Clients and federation discovery services query this endpoint regularly.

Test it:

curl https://pixelfed.yourdomain.com/api/v1/instance

Healthy response (truncated):

{
  "uri": "pixelfed.yourdomain.com",
  "title": "My Pixelfed",
  "version": "3.5.5 (compatible; Pixelfed 0.11.9)",
  "stats": {
    "user_count": 28,
    "status_count": 410
  }
}

Set up the API monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to https://pixelfed.yourdomain.com/api/v1/instance.
3. Set Expected status code to 200.
4. Under Advanced → Keyword check, add:
   • Keyword present: "uri"
   • Keyword absent: "error"
5. Save.

Step 3: Horizon Queue Worker Health via Heartbeat

Pixelfed relies on Laravel Horizon to process federation deliveries, incoming ActivityPub events, and media transformations. When Horizon stops — due to Redis loss, a crashed worker, or memory exhaustion — photos stop federating and incoming follows never arrive, but the web UI remains fully functional.

Step 3a: Create the Vigilmon heartbeat monitor.

1. Click New Monitor → Heartbeat in Vigilmon.
2. Set Name to Pixelfed Horizon Worker.
3. Set Expected interval to 5 minutes.
4. Set Grace period to 2 minutes.
5. Save and copy the unique heartbeat ping URL (e.g., https://vigilmon.online/heartbeat/abc123).

Step 3b: Schedule a periodic ping from Horizon.

Add a scheduled command to your Laravel app. In app/Console/Kernel.php:

protected function schedule(Schedule $schedule): void
{
    $schedule->call(function () {
        Http::get('https://vigilmon.online/heartbeat/abc123');
    })->everyFiveMinutes()->name('vigilmon-heartbeat');
}

Run php artisan schedule:run via cron every minute (standard Laravel setup):

* * * * * cd /var/www/pixelfed && php artisan schedule:run >> /dev/null 2>&1

Vigilmon alerts you when the ping stops arriving, indicating Horizon has stopped or Redis is unavailable.

Step 4: Monitor the Federation Endpoint

Pixelfed's ActivityPub federation uses the .well-known/webfinger endpoint for user discovery across the fediverse. Other servers query this endpoint to look up your users. If it fails, your instance becomes invisible to the rest of the fediverse.

Test it:

curl "https://pixelfed.yourdomain.com/.well-known/webfinger?resource=acct:admin@pixelfed.yourdomain.com"

Healthy response:

{
  "subject": "acct:admin@pixelfed.yourdomain.com",
  "links": [...]
}

Set up the monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to https://pixelfed.yourdomain.com/.well-known/webfinger?resource=acct:admin@pixelfed.yourdomain.com.
3. Set Expected status code to 200.
4. Under Advanced → Keyword check, add keyword present: subject.
5. Save.

Replace admin with a real account username on your instance.

Step 5: SSL Certificate Monitoring

ActivityPub federation is HTTPS-only — other Pixelfed and Mastodon instances will refuse to interact with your server if your certificate is expired. Vigilmon automatically monitors SSL certificate validity on all HTTPS monitors.

1. Open your Pixelfed web UI monitor in Vigilmon.
2. Under Advanced → SSL, ensure Alert before expiry is enabled (default: 14 days).
3. Save.

Step 6: Alert Channels

Go to Notifications → New Channel in Vigilmon and configure:

• Email — for your instance admin
• Webhook — for Slack, Discord, or Matrix

A Horizon heartbeat alert looks like:

🔴 DOWN: Pixelfed Horizon Worker (Heartbeat)
No ping received in the last 7 minutes (expected every 5)
Triggered: 2026-03-01 09:22 UTC

What You've Built

| Scenario | How Vigilmon catches it | |---|---| | PHP-FPM or Laravel crash | HTTP monitor detects non-200 from web UI | | Database connection failure | /api/v1/instance returns error | | Horizon worker stopped | Heartbeat monitor misses scheduled ping | | Redis unavailable | Horizon heartbeat stops; queue jobs pile up | | WebFinger / federation broken | .well-known/webfinger monitor fails | | SSL certificate expired | HTTPS monitor reports TLS error | | DNS misconfiguration | HTTP monitor detects resolution failure |

Running a Pixelfed instance means your community's photos and memories depend on your infrastructure staying healthy. Vigilmon's layered monitoring gives you visibility into every component — so you know about problems before your users notice their posts aren't federating.

Start monitoring your Pixelfed instance today — register free at vigilmon.online.