Monitoring GNU Social with Vigilmon

GNU Social is one of the original federated social network platforms — a PHP/Symfony2 application that implements both OStatus and ActivityPub, letting your instance communicate with Mastodon, Pleroma, and the wider Fediverse. Self-hosting it means you own the data and the uptime. Vigilmon gives you the external monitoring layer to know when something breaks before your users do.

What You'll Set Up

• HTTP uptime monitor for the main web interface
• PHP-FPM process pool health via a custom status endpoint
• MySQL/MariaDB database connectivity check
• Federation endpoint and WebFinger discovery monitoring
• Background queue worker heartbeat
• Scheduled cleanup job heartbeat
• SSL certificate expiry alerts

Prerequisites

• GNU Social installed and running (Apache/nginx + PHP-FPM + MySQL/MariaDB)
• Shell access to the server
• A free Vigilmon account

Step 1: Monitor Web Server Availability

GNU Social runs behind Apache or nginx on port 80/443. The root endpoint returns the public timeline and is the primary availability signal.

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter your instance URL: https://social.yourdomain.com
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Enable Monitor SSL certificate and set the expiry alert to 21 days.
7. Click Save.

For a richer signal, add a keyword check on the home page response. GNU Social renders <div id="content"> on every page — if this disappears, the app is broken even when the web server returns 200:

1. Open the monitor settings.
2. Under Keyword check, enter id="content".
3. Save.

Step 2: Add a PHP-FPM Health Check Endpoint

PHP-FPM's built-in status page exposes pool worker counts and request queues. Enable it so Vigilmon can probe PHP-FPM health directly.

Enable the status page in your PHP-FPM pool config (/etc/php/8.x/fpm/pool.d/www.conf):

pm.status_path = /fpm-status

Expose it in nginx (restrict to localhost to avoid public exposure):

location = /fpm-status {
    allow 127.0.0.1;
    deny all;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    fastcgi_pass unix:/run/php/php8.x-fpm.sock;
}

Reload PHP-FPM and nginx:

systemctl reload php8.x-fpm
systemctl reload nginx

Now create a small health check script that Vigilmon can reach over HTTPS. Add this as a PHP file in your web root (e.g. /var/www/gnusocial/health.php):

<?php
// health.php — composite health check for GNU Social
header('Content-Type: application/json');

$checks = [];
$status = 200;

// PHP-FPM: try to reach the status page via loopback
$fpm = @file_get_contents('http://127.0.0.1/fpm-status');
$checks['php_fpm'] = ($fpm !== false && strpos($fpm, 'pool:') !== false) ? 'ok' : 'error';

// MySQL: check using PDO
try {
    $dsn = 'mysql:host=127.0.0.1;dbname=gnusocial;charset=utf8mb4';
    $pdo = new PDO($dsn, DB_USER, DB_PASS, [PDO::ATTR_TIMEOUT => 2]);
    $pdo->query('SELECT 1');
    $checks['database'] = 'ok';
} catch (Exception $e) {
    $checks['database'] = 'error';
    $status = 503;
}

if ($checks['php_fpm'] === 'error') {
    $status = 503;
}

http_response_code($status);
echo json_encode(['status' => $status === 200 ? 'ok' : 'degraded', 'checks' => $checks]);

Update the database credentials to match your config.php values (DB_USER, DB_PASS, and the database name). Then add a second Vigilmon monitor pointing to https://social.yourdomain.com/health.php.

Step 3: Monitor Federation and WebFinger Endpoints

GNU Social's federation relies on several well-known endpoints. If these are broken, your instance can't federate even while the web UI appears fine.

Add an HTTP monitor for each critical federation URL:

WebFinger discovery (used by remote instances to find your users):

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

Expected status: 200. Add a keyword check for "subject" in the response body.

ActivityPub actor endpoint (used by ActivityPub-compatible servers):

https://social.yourdomain.com/user/1

Add the header check: Accept: application/activity+json. Expected status: 200.

OStatus Salmon endpoint (for OStatus federation):

https://social.yourdomain.com/main/salmon/user/1

Expected status: 200 or 405 (method not allowed on GET is acceptable — it means the endpoint exists).

In Vigilmon, create one HTTP monitor per endpoint with a 5-minute check interval. Federation endpoints are less critical than the main UI, so a 5-minute interval avoids noise while still catching prolonged outages.

Step 4: Heartbeat Monitoring for the Queue Worker

GNU Social processes incoming federation messages and notifications through a background daemon (php scripts/queuedaemon.php). If it stops, your instance will stop receiving federated posts even though the web UI stays up.

Set up a heartbeat monitor:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set expected interval to 10 minutes.
3. Copy the heartbeat URL.
4. Create a wrapper script at /usr/local/bin/gnusocial-queue-heartbeat.sh:

#!/bin/bash
# Ping Vigilmon after confirming the queue daemon is alive
DAEMON_PID=$(pgrep -f "queuedaemon.php")
if [ -n "$DAEMON_PID" ]; then
    curl -fsS --retry 3 "https://vigilmon.online/heartbeat/YOUR_HEARTBEAT_TOKEN" > /dev/null
else
    echo "Queue daemon not running" >&2
    exit 1
fi

Make it executable and add a cron job:

chmod +x /usr/local/bin/gnusocial-queue-heartbeat.sh

# Add to root crontab
*/10 * * * * /usr/local/bin/gnusocial-queue-heartbeat.sh

If the queue daemon crashes and is not restarted, the heartbeat script exits with an error and never pings Vigilmon. After 10 minutes, Vigilmon fires an alert.

Step 5: Heartbeat for Scheduled Cleanup Jobs

GNU Social's maintenance scripts (scripts/delete_orphan_files.php, scripts/gcexpirations.php) clean up old session data, expired tokens, and orphaned media. If they stop running, disk usage climbs silently.

Wrap them in heartbeat pings. Create /etc/cron.daily/gnusocial-maintenance:

#!/bin/bash
set -e

cd /var/www/gnusocial

# Run cleanup scripts
php scripts/delete_orphan_files.php >> /var/log/gnusocial/maintenance.log 2>&1
php scripts/gcexpirations.php >> /var/log/gnusocial/maintenance.log 2>&1

# Ping heartbeat only if all scripts succeeded
curl -fsS --retry 3 "https://vigilmon.online/heartbeat/YOUR_CLEANUP_TOKEN" > /dev/null

chmod +x /etc/cron.daily/gnusocial-maintenance

Create a second Vigilmon Cron Heartbeat monitor with a 25 hours expected interval. A one-day cron that misses a day is caught within the 25-hour window.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon.
2. Add an email address or Slack webhook.
3. On the main web monitor, set Consecutive failures before alert to 2 — this prevents false alarms from transient nginx hiccups during PHP-FPM restarts.
4. On federation endpoint monitors, set Consecutive failures before alert to 3 — federation can tolerate brief outages more gracefully than the main UI.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web availability | https://social.yourdomain.com | nginx/Apache down, PHP crash | | Health endpoint | /health.php | PHP-FPM pool exhaustion, DB connectivity loss | | WebFinger | /.well-known/webfinger?resource=… | Identity discovery broken | | ActivityPub actor | /user/1 | AP federation broken | | Queue daemon heartbeat | Vigilmon heartbeat URL | Background queue worker crash | | Cleanup job heartbeat | Vigilmon heartbeat URL | Maintenance scripts failing silently | | SSL certificate | Main domain | Let's Encrypt renewal failure |

GNU Social is battle-tested federation software, but self-hosting means owning every layer of the stack. With Vigilmon watching your web server, database, federation endpoints, and background workers, you'll know about failures before they impact your users or your instance's standing in the Fediverse.

Get started free at vigilmon.online.