tutorial

Akkoma Monitoring with Vigilmon: Federation Health, Oban Queues & SSL Alerts

Monitor your self-hosted Akkoma federated microblogging server with Vigilmon — cover web UI availability, the instance health API, federation endpoints, Oban job queue heartbeats, and SSL certificate alerts.

Your Akkoma instance went silent at 3 AM. The Oban job queue stalled, federation stopped delivering posts to Mastodon followers, and your users woke up to a timeline frozen in the past. No alert fired. You found out six hours later when someone emailed you.

Akkoma is a Pleroma-fork federated microblogging server built on Elixir and OTP. It speaks ActivityPub, federates with Mastodon, Misskey, and the broader Fediverse, and handles a surprising amount of background work through Oban job queues — media processing, federation delivery, notification dispatch. When any of those pieces fails silently, your users notice before you do.

Vigilmon gives you the external monitoring layer that catches Akkoma downtime, federation failures, and queue stalls before they become hours-long incidents.

What You'll Build

  • A Vigilmon HTTP monitor on Akkoma's instance health API
  • A federation endpoint check to detect split-brain federation
  • A web UI availability monitor with keyword detection
  • An Oban job queue heartbeat monitor
  • SSL certificate expiry alerts

Prerequisites

  • A self-hosted Akkoma instance (Akkoma 3.x or later recommended)
  • A free account at vigilmon.online

Step 1: Monitor the Instance Health API

Akkoma exposes a Mastodon-compatible instance endpoint at /api/v1/instance. This endpoint returns instance metadata and responds only when Akkoma is up and the database is reachable.

Test it:

curl https://your-akkoma.example.com/api/v1/instance

Expected response (abbreviated):

{
  "uri": "your-akkoma.example.com",
  "title": "My Akkoma Instance",
  "version": "3.13.0 (compatible; Akkoma)",
  "stats": {
    "user_count": 42,
    "status_count": 1834,
    "domain_count": 512
  }
}

A 200 response with a uri field confirms Akkoma is up and the PostgreSQL database is answering queries. If Akkoma crashes, the database goes away, or the Elixir application fails to start, this endpoint returns a non-200 status or times out.

Set up the Vigilmon monitor:

  1. Log in to Vigilmon and click New Monitor → HTTP.
  2. Set URL to https://your-akkoma.example.com/api/v1/instance.
  3. Set Check interval to 60 seconds.
  4. Set Expected status code to 200.
  5. Under Advanced → JSON body assertion, add:
    • Path: uri
    • Operator: exists
  6. Save the monitor.

Vigilmon will now check your Akkoma API every minute from multiple geographic regions.

Step 2: Federation Endpoint Check

Akkoma participates in ActivityPub federation through its federation API. The NodeInfo endpoint and the WebFinger endpoint are the first things remote servers check when deciding whether to federate with you.

Check NodeInfo:

curl https://your-akkoma.example.com/.well-known/nodeinfo

Expected response:

{
  "links": [
    {
      "rel": "http://nodeinfo.diaspora.software/ns/schema/2.1",
      "href": "https://your-akkoma.example.com/nodeinfo/2.1"
    }
  ]
}

If this endpoint is broken, other Fediverse servers will fail to discover your instance capabilities and may stop delivering posts to your users.

Add a federation monitor in Vigilmon:

  1. Click New Monitor → HTTP.
  2. Set URL to https://your-akkoma.example.com/.well-known/nodeinfo.
  3. Set Check interval to 5 minutes (federation issues don't need 1-minute resolution).
  4. Set Expected status code to 200.
  5. Under Advanced → Keyword check:
    • Keyword present: nodeinfo.diaspora.software
  6. Save.

You can also monitor the WebFinger endpoint used by remote servers to look up your users:

https://your-akkoma.example.com/.well-known/webfinger?resource=acct:admin@your-akkoma.example.com

Add a second HTTP monitor on this URL, checking for a 200 response with the keyword subject.

Step 3: Web UI Availability

Akkoma's web frontend is served separately from the API. A broken asset pipeline, a misconfigured Nginx reverse proxy, or a failed static file deployment can take down the UI while the API stays healthy.

  1. Click New Monitor → HTTP in Vigilmon.
  2. Set URL to https://your-akkoma.example.com/ (your public homepage).
  3. Set Check interval to 60 seconds.
  4. Set Expected status code to 200.
  5. Under Advanced → Keyword check:
    • Keyword present: your instance title (e.g., "My Akkoma Instance") or akkoma
    • Keyword absent: "Internal Server Error", "502 Bad Gateway"
  6. Save.

This catches the class of failures where Akkoma's Elixir process is healthy but the frontend delivery is broken.

Step 4: Oban Job Queue Heartbeat

Akkoma relies on Oban (an Elixir job queue backed by PostgreSQL) for all background work: delivering ActivityPub posts to remote servers, processing incoming activities, sending notifications, and pruning old data. When the Oban queue stalls — due to a PostgreSQL advisory lock issue, a worker crash loop, or a configuration error — federation delivery silently stops. Posts appear to send but never arrive at remote instances.

Vigilmon's heartbeat monitor solves this. You configure Akkoma to send a periodic HTTP ping to Vigilmon, and Vigilmon alerts you if the ping stops arriving.

Set Up the Heartbeat Monitor

  1. In Vigilmon, click New Monitor → Heartbeat.
  2. Set the Name to Akkoma Oban Queue.
  3. Set Expected interval to 10 minutes with a 5 minute grace period.
  4. Save the monitor and copy the Heartbeat URL (looks like https://vigilmon.online/heartbeat/<your-token>).

Configure Akkoma to Ping Vigilmon

Akkoma supports custom Oban job workers. Add a periodic job that pings the Vigilmon heartbeat URL. Create a custom worker module in your Akkoma config:

# In config/prod.secret.exs or your Akkoma custom worker file
# Add to your Oban cron configuration:

config :pleroma, Oban,
  queues: [
    # ... your existing queues
  ],
  cron: [
    # ... your existing cron jobs
    {"*/10 * * * *", Pleroma.Workers.VigilmonHeartbeatWorker}
  ]

Create the worker file at lib/pleroma/workers/vigilmon_heartbeat_worker.ex:

defmodule Pleroma.Workers.VigilmonHeartbeatWorker do
  use Oban.Worker, queue: :background

  @heartbeat_url "https://vigilmon.online/heartbeat/<your-token>"

  @impl Oban.Worker
  def perform(_job) do
    Pleroma.HTTP.get(@heartbeat_url)
    :ok
  end
end

Replace <your-token> with your actual Vigilmon heartbeat token. Restart Akkoma after this change.

Now if the Oban queue stalls and this worker stops running, Vigilmon will alert you after 15 minutes (10-minute interval + 5-minute grace). You catch silent queue failures before your users notice that federation has stopped.

Step 5: SSL Certificate Alerts

Akkoma serves over HTTPS and federates using TLS. An expired SSL certificate breaks both the web UI for your users and federation delivery from remote servers — other instances will refuse to connect and your posts will stop federating across the Fediverse.

Vigilmon's HTTPS monitors automatically check SSL certificate validity on every request. To add an explicit certificate expiry alert:

  1. In your existing HTTP monitor for /api/v1/instance, go to Edit.
  2. Under Advanced → SSL certificate, enable Alert when certificate expires within and set the threshold to 14 days.
  3. Save.

You'll receive an alert 14 days before expiry, giving you time to renew via Let's Encrypt or your certificate provider before federation breaks.

Step 6: Alert Channels

Go to Notifications → New Channel in Vigilmon and configure:

  • Email — direct alerts to your admin inbox
  • Webhook — post to a Discord server or Slack workspace for your admin team

A federation endpoint failure alert looks like:

🔴 DOWN: your-akkoma.example.com NodeInfo
/.well-known/nodeinfo returned 502
Keyword "nodeinfo.diaspora.software" not found
Region: EU-Central
Triggered: 2026-01-15 03:42 UTC

An Oban queue heartbeat miss looks like:

🔴 HEARTBEAT MISSED: Akkoma Oban Queue
Last ping: 18 minutes ago (expected every 10 minutes)

What You've Built

| Scenario | How Vigilmon catches it | |---|---| | Akkoma process crash | /api/v1/instance returns non-200 | | PostgreSQL database unreachable | Instance API times out or errors | | Federation discovery broken | NodeInfo endpoint check fails | | WebFinger lookup broken | WebFinger monitor detects non-200 | | Web UI delivery broken (Nginx/frontend) | Homepage keyword check fails | | Oban queue stall (silent federation failure) | Heartbeat monitor misses expected ping | | SSL certificate expiry | Certificate expiry alert fires 14 days before | | Reverse proxy (Nginx/Caddy) down | HTTP monitor sees 502/504 |

Running a Fediverse instance means accepting responsibility for uptime that affects not just your users but also your federation partners. A stalled Oban queue or an expired certificate doesn't just inconvenience your users — it breaks federation for everyone trying to interact with your instance.

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

Monitor your app with Vigilmon

Free plan — 5 monitors, no credit card required. Up and running in 60 seconds.

Start free →
← Back to all articles