PeerTube Monitoring with Vigilmon: Web UI, API Health, Video Upload & Transcoding Checks

A creator uploaded a video to your PeerTube instance during peak hours. The upload completed successfully, but the transcoding queue had been silently stuck for three hours — a ffmpeg worker had crashed and the job was just sitting there. Viewers who clicked the video saw a loading spinner. The creator assumed their upload had failed and emailed you in frustration.

PeerTube is a self-hosted, federated video platform built on ActivityPub. It handles video uploads, transcoding into multiple resolutions, HLS streaming, federation with other PeerTube instances, and live streaming. Each layer is a potential failure point. Vigilmon gives you external monitoring across all of them so you catch problems before creators and viewers do.

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

What You'll Build

• A Vigilmon HTTP monitor on the PeerTube web UI
• An API health check using PeerTube's /api/v1/ping endpoint
• A video upload API availability check
• A Vigilmon heartbeat monitor for transcoding job queue health
• SSL certificate expiry alerts

Prerequisites

• A running PeerTube instance (v6.x recommended)
• A free account at vigilmon.online

Step 1: Monitor the PeerTube Web UI

The PeerTube homepage is the first thing viewers and creators see. A healthy homepage confirms that Nginx, the Node.js server process, and the PostgreSQL database are all reachable.

Test it:

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

You should see 200 OK. PeerTube's index page renders dynamic content from the database, so a successful response implies database connectivity.

Set up the Vigilmon monitor:

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

The keyword check prevents false positives from Nginx error pages that might return 200 with generic content.

Step 2: Monitor the /api/v1/ping Health Endpoint

PeerTube provides a dedicated /api/v1/ping endpoint specifically designed for health checks. It returns a simple JSON response confirming the API layer is alive.

Test it:

curl https://peertube.yourdomain.com/api/v1/ping

Healthy response:

{
  "ping": "pong",
  "serverVersion": "6.0.4",
  "serverCommit": "abc123"
}

A non-200 response or missing ping field means the Node.js server process is unhealthy.

Set up the API ping monitor:

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

This endpoint requires no authentication and is the recommended first check for any PeerTube health monitoring setup.

Step 3: Monitor the Video Upload API

Video uploads are PeerTube's core function. A broken upload API — caused by disk space exhaustion, file permission errors, or object storage misconfiguration — means creators can't publish content even if the homepage looks fine.

PeerTube's video list endpoint is a lightweight proxy for upload API health:

curl "https://peertube.yourdomain.com/api/v1/videos?count=1&sort=-publishedAt"

Healthy response includes a data array with recent videos. A 500 error here often indicates database issues or a broken storage backend.

Set up the monitor:

1. Click New Monitor → HTTP in Vigilmon.
2. Set URL to https://peertube.yourdomain.com/api/v1/videos?count=1&sort=-publishedAt.
3. Set Expected status code to 200.
4. Under Advanced → Keyword check, add:
   • Keyword present: "data"
   • Keyword absent: "error"
5. Save.

For a more direct upload test, you can use a dedicated monitoring account with the PeerTube API, but the video list endpoint is sufficient for most production setups.

Step 4: Transcoding Queue Health via Heartbeat

PeerTube's transcoding pipeline converts uploaded videos into HLS streams at multiple resolutions. This runs as a separate job queue using @peertube/peertube-runner or PeerTube's built-in ffmpeg queue. When transcoding stalls, uploads appear to succeed but videos are never playable.

Use a Vigilmon heartbeat monitor to verify the transcoding process is alive:

Step 4a: Create the Vigilmon heartbeat monitor.

1. Click New Monitor → Heartbeat in Vigilmon.
2. Set Name to PeerTube Transcoding Queue.
3. Set Expected interval to 10 minutes.
4. Set Grace period to 5 minutes.
5. Save and copy the heartbeat ping URL (e.g., https://vigilmon.online/heartbeat/xyz789).

Step 4b: Add a cron job to ping Vigilmon.

Add a cron entry on your PeerTube server:

crontab -e

*/10 * * * * curl -sf https://vigilmon.online/heartbeat/xyz789 -o /dev/null

For a smarter check that only pings if the transcoding queue is actually processing, you can wrap it with a PeerTube API call that checks for pending jobs:

*/10 * * * * \
  JOBS=$(curl -sf "https://peertube.yourdomain.com/api/v1/jobs/waiting?jobType=video-transcoding&count=1" \
    -H "Authorization: Bearer <admin-token>" | jq '.total'); \
  [ "$JOBS" -lt 100 ] && curl -sf https://vigilmon.online/heartbeat/xyz789 -o /dev/null

This pings Vigilmon only when the waiting transcoding queue is under 100 jobs — if it grows beyond that, the heartbeat stops, alerting you to a stuck queue.

Step 5: SSL Certificate Monitoring

PeerTube uses HTTPS for all API calls, HLS streaming, and ActivityPub federation. An expired certificate breaks video playback in browsers and breaks federation with other PeerTube instances. Vigilmon automatically checks SSL validity on all HTTPS monitors.

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

If you use a wildcard certificate or a separate cert for your object storage CDN subdomain, add a separate HTTPS monitor for that subdomain as well.

Step 6: Alert Channels

Go to Notifications → New Channel in Vigilmon and configure:

• Email — direct alerts to your platform admin
• Webhook — post to Slack, Discord, or Matrix

A stuck transcoding queue alert looks like:

🔴 DOWN: PeerTube Transcoding Queue (Heartbeat)
No ping received in the last 15 minutes (expected every 10)
Triggered: 2026-04-05 16:22 UTC

A recovered alert:

✅ RECOVERED: PeerTube Transcoding Queue
Downtime: 28 minutes

Step 7: Status Page

Go to Status Pages → New Status Page in Vigilmon. Add all monitors, name them clearly (e.g., "PeerTube Web UI", "PeerTube API", "Video Transcoding"), and share the status page URL with your creator community. Transparent status communication builds trust when incidents happen.

What You've Built

| Scenario | How Vigilmon catches it | |---|---| | Node.js process crash | HTTP monitor detects 502 from Nginx | | Database connection failure | /api/v1/ping returns non-200 | | Video list API broken | Videos API HTTP monitor fails | | Transcoding queue stuck | Heartbeat monitor misses scheduled ping | | Disk full (upload broken) | Videos API returns 500 or 503 | | SSL certificate expired | HTTPS monitor reports TLS error | | DNS misconfiguration | HTTP monitor detects resolution failure |

PeerTube's federation and transcoding pipeline make it more operationally complex than a simple web app. Silent failures in the transcoding queue or ActivityPub delivery are the hardest to catch without external monitoring. Vigilmon's heartbeat and HTTP monitors give you visibility across every layer so your creators can upload and your viewers can watch without interruption.

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