Monitoring Pleroma with Vigilmon

Pleroma is a lightweight ActivityPub-compatible decentralized microblogging platform built with Elixir/OTP. It runs on a fraction of the memory and CPU that Mastodon requires, making it ideal for single-user instances on low-power hardware like a Raspberry Pi or small VPS. Pleroma is Mastodon-API-compatible, so users can connect with Tusky, Pinafore, and other Mastodon-compatible clients. Its popular fork Akkoma extends Pleroma with additional features. Despite its efficiency, Pleroma's Oban job queue — which handles federation, media processing, and notification delivery — can stall after database hiccups or configuration errors. Vigilmon gives you uptime monitoring for the Pleroma web UI, API health checks, background worker alerts, and SSL certificate expiry notifications — so federation problems surface before your users start noticing missing posts.

What You'll Set Up

HTTP uptime monitor for the Pleroma web UI
API availability check for the /api/v1/instance Mastodon-compatible endpoint
Application health check via the /healthcheck endpoint
SSL certificate expiry alerts for your Pleroma domain
Heartbeat monitoring for Pleroma's Oban background worker queue

Prerequisites

Pleroma (or Akkoma) running on port 4000 or behind an Nginx/Caddy reverse proxy
Access to the /healthcheck endpoint (enabled by default in Pleroma config)
A free Vigilmon account

Step 1: Monitor the Pleroma Web UI

Pleroma serves its frontend (Pleroma-FE or Soapbox-FE) from the root path. A basic HTTP check confirms the Elixir application is running and the reverse proxy is forwarding traffic correctly.

Log in to vigilmon.online and click Add Monitor.
Set Type to HTTP / HTTPS.
Enter your Pleroma URL: https://pleroma.yourdomain.com (or http://yourserver:4000 if checking the raw Elixir port).
Set Check interval to 1 minute.
Set Expected HTTP status to 200.
Click Save.

Pleroma's frontend is a single-page application, so the root / returns the HTML shell. Any non-200 response at this path means either the Elixir process has crashed or Nginx/Caddy has lost its upstream connection.

Step 2: Monitor the `/api/v1/instance` API Endpoint

Pleroma exposes Mastodon-compatible API endpoints including /api/v1/instance, which returns JSON metadata about your instance — software name, version, description, and configuration. A successful response confirms the application layer is healthy beyond just serving static files.

In Vigilmon, click Add Monitor → HTTP / HTTPS.
Enter URL: https://pleroma.yourdomain.com/api/v1/instance
Set Method to GET.
Set Expected HTTP status to 200.
Set Expected response body contains to "pleroma" (or "akkoma" for Akkoma forks — always present in the version or title field).
Click Save.

A healthy Pleroma instance responds in under 100ms for this unauthenticated endpoint. Slow or failed responses here typically indicate database connectivity issues even when the frontend loads from cache.

Step 3: Monitor the `/healthcheck` Endpoint

Pleroma includes a built-in /healthcheck endpoint that returns a JSON object with background worker queue status and database connectivity information. This is the most valuable monitoring target on a Pleroma instance — it exposes internal health that the web UI and instance API cannot reveal.

In Vigilmon, click Add Monitor → HTTP / HTTPS.
Enter URL: https://pleroma.yourdomain.com/healthcheck
Set Method to GET.
Set Expected HTTP status to 200.
Set Expected response body contains to "healthy":true.
Click Save.

The /healthcheck response looks like this when the system is healthy:

{
  "healthy": true,
  "db_connected": true,
  "background_jobs": true,
  "job_queue_count": 0
}

If "healthy":false appears in the response body, Vigilmon will alert you. Common causes include a disconnected database, a stalled Oban worker pool, or an exhausted connection pool. The endpoint also reports job_queue_count — a persistently high value indicates backlogged federation even when the instance is technically "healthy."

Step 4: SSL Certificate Alerts

Pleroma is typically deployed behind an Nginx or Caddy reverse proxy that terminates TLS. Let's Encrypt certificates need periodic renewal — Certbot and Caddy handle this automatically, but misconfigurations (blocked port 80, expired DNS, changed IP) can cause silent renewal failures.

Open the HTTP / HTTPS monitor created in Step 1.
Enable Monitor SSL certificate under the SSL section.
Set Alert when certificate expires in less than 21 days.
Click Save.

A 21-day alert window gives you three automatic renewal cycles before the certificate actually expires. If your Pleroma instance uses a wildcard certificate, add a dedicated SSL monitor for the exact domain serving your Pleroma frontend, since wildcards are issued at the parent domain level and Vigilmon checks the certificate presented to the specific subdomain you configure.

Step 5: Heartbeat Monitoring for Oban Background Workers

Pleroma's Oban job queue processes federation delivery, incoming activity processing, media cleanup, and notification delivery. A stalled Oban worker pool — caused by database connection exhaustion, a crashed BEAM process, or misconfigured queue limits — degrades federation without taking down the web UI. Users will see the site as "up" while messages stop federating out.

Use Vigilmon's cron heartbeat to verify Oban is actually processing jobs:

In Vigilmon, click Add Monitor → Cron Heartbeat.
Set the expected ping interval to 10 minutes (Oban typically drains small queues in seconds, so a 10-minute window catches stalls early).
Copy the heartbeat URL (e.g. https://vigilmon.online/heartbeat/abc123).

Add a cron job that pings the heartbeat URL only when the /healthcheck endpoint reports healthy:

# /etc/cron.d/pleroma-heartbeat
# Every 10 minutes — ping Vigilmon only if Pleroma healthcheck passes
*/10 * * * * pleroma \
  curl -sf https://pleroma.yourdomain.com/healthcheck | grep -q '"healthy":true' \
  && curl -s https://vigilmon.online/heartbeat/abc123

If the healthcheck fails or is unreachable, the && short-circuits and the heartbeat ping is suppressed — Vigilmon alerts after 10 minutes of silence.

For deeper Oban monitoring, you can also instrument Pleroma's Elixir application directly by adding a custom Oban worker that pings the heartbeat URL after processing a scheduled no-op job:

# In a custom worker module loaded by your Pleroma installation
defmodule MyInstance.HeartbeatWorker do
  use Oban.Worker, queue: :background

  @impl Oban.Worker
  def perform(_job) do
    HTTPoison.get("https://vigilmon.online/heartbeat/abc123")
    :ok
  end
end

Schedule it with a periodic Oban cron entry in your config.exs.

Step 6: Configure Alert Channels

Go to Alert Channels in Vigilmon and add email, Slack, Discord webhook, or PagerDuty.
Set Consecutive failures before alert to 2 on the web UI monitor — Pleroma's Elixir/OTP supervisor restarts crashed processes in milliseconds, and a single missed probe during a crash-and-restart cycle is not unusual.
Set Consecutive failures before alert to 1 on the /healthcheck monitor — a failed healthcheck is always a real issue.
Add a Maintenance window in Vigilmon during Pleroma version upgrades, which require a brief stop and restart of the Elixir release.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://pleroma.yourdomain.com/ | Elixir crash, Nginx/Caddy proxy failure | | Instance API | /api/v1/instance (GET) | Database connectivity issues | | Healthcheck | /healthcheck (GET) | Oban worker stall, DB connection pool | | SSL certificate | Pleroma domain | Let's Encrypt renewal failure | | Cron heartbeat | Heartbeat URL | Federation queue backlog, Oban stall |

Pleroma's low resource footprint makes it the go-to choice for self-hosted Fediverse instances on modest hardware — but that same efficiency means problems like a stalled Oban queue are harder to notice without dedicated monitoring. With Vigilmon watching the web UI, API endpoints, healthcheck, and background workers, you get full observability over your Pleroma instance with minimal overhead.