tutorial

Monitoring RomM Game Library with Vigilmon

RomM is a self-hosted ROM management platform — but a crashed API or broken metadata integration leaves your retro game library inaccessible. Here's how to monitor RomM availability, database connectivity, ROM scan jobs, and IGDB integration with Vigilmon.

RomM is a self-hosted ROM management platform that organizes your retro game collection with IGDB metadata, cover art, and a polished web UI. When it's working, it's the best way to browse your NES, SNES, PS1, and N64 library from any device. When it's not — because PostgreSQL went down, the ROM filesystem became read-only, or an IGDB API key expired — your entire collection becomes inaccessible. Vigilmon monitors every layer of RomM so you know about failures before your next gaming session.

What You'll Set Up

  • HTTP uptime monitor for the RomM web interface (port 8080)
  • PostgreSQL database connectivity monitoring
  • ROM file storage backend health (filesystem read-write)
  • IGDB and MobyGames API connectivity
  • ROM scan job heartbeat monitoring
  • User authentication service health
  • SSL certificate expiry alerts

Prerequisites

  • RomM running and accessible (default port 8080)
  • A free Vigilmon account

Step 1: Monitor the RomM Web Interface

RomM serves its Vue.js frontend and FastAPI backend at port 8080. Add a Vigilmon HTTP monitor:

  1. Log in to vigilmon.online and click Add Monitor.
  2. Set Type to HTTP / HTTPS.
  3. Enter your RomM URL: https://romm.yourdomain.com (or http://your-server-ip:8080).
  4. Set Check interval to 1 minute.
  5. Set Expected HTTP status to 200.
  6. Click Save.

This covers the complete request path through your reverse proxy, the FastAPI application server, and static asset delivery.

Step 2: Monitor the RomM API Health Endpoint

RomM's FastAPI backend exposes a dedicated health endpoint. Monitor it separately from the frontend so you can distinguish a Vue.js static file issue from a backend API failure:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://romm.yourdomain.com/api/heartbeat (FastAPI health path — confirm the exact route in your RomM version's API docs or check /api/docs).
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 1 minute.
  5. Click Save.

A 200 from the heartbeat endpoint confirms the Python/FastAPI process is alive and serving requests.

Step 3: Monitor PostgreSQL Database Connectivity

RomM stores all ROM metadata — titles, platforms, cover art URLs, user collections, ratings, and play history — in PostgreSQL. If the database goes down or the connection pool exhausts, the RomM API returns 500 errors for every data-backed request.

Add a TCP monitor for PostgreSQL:

  1. Click Add Monitor → TCP Port.
  2. Set Hostname to your PostgreSQL host (e.g. localhost or your DB container name).
  3. Set Port to 5432.
  4. Set Check interval to 1 minute.
  5. Click Save.

For a deeper health check, add a script that actually queries the database and pings a Vigilmon heartbeat on success:

#!/bin/bash
# romm-db-health.sh
PGPASSWORD=yourpassword psql -h localhost -U romm -d romm -c "SELECT 1" -q >/dev/null 2>&1
if [ $? -eq 0 ]; then
  curl -s https://vigilmon.online/heartbeat/db-heartbeat-url
fi

Schedule with cron every 2 minutes. This catches scenarios where the PostgreSQL port is open but the database itself is in recovery mode and rejecting queries.

Step 4: Monitor ROM File Storage

RomM reads and writes ROM files from a configured directory (local filesystem, NFS mount, or SMB share). If the mount drops or the directory becomes read-only, newly added ROMs vanish and downloads fail silently.

Create a write-health heartbeat:

#!/bin/bash
# rom-storage-health.sh
ROM_DIR="/path/to/romm/library"
TEST_FILE="$ROM_DIR/.vigilmon_write_test"

if touch "$TEST_FILE" 2>/dev/null && rm "$TEST_FILE" 2>/dev/null; then
  curl -s https://vigilmon.online/heartbeat/storage-heartbeat-url
else
  echo "ROM storage not writable: $ROM_DIR" >&2
fi
  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set expected interval to 5 minutes.
  3. Schedule the script with cron: */5 * * * * /opt/romm/rom-storage-health.sh.

A missed heartbeat means your ROM library is on a degraded or disconnected storage backend.

Step 5: Monitor IGDB API Connectivity

RomM uses the Internet Games Database (IGDB) API to fetch game metadata, cover art, and platform information when you scan new ROMs. IGDB requires a Twitch/IGDB client credential pair with a token that expires periodically. If the token expires or the IGDB API is unreachable, ROM scans complete but return no metadata.

Add an HTTP monitor for the IGDB API endpoint:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://api.igdb.com/v4/games (a HEAD request to confirm reachability).
  3. Set Request method to HEAD.
  4. Set Expected HTTP status to 200 or 401 (401 means the API is reachable but your test has no credentials — that's fine; 503 or timeout means IGDB is down).
  5. Set Check interval to 5 minutes.

For credential expiry detection, add a script that uses your actual IGDB credentials:

#!/bin/bash
# igdb-health.sh
RESPONSE=$(curl -sf -o /dev/null -w "%{http_code}" \
  -H "Client-ID: $IGDB_CLIENT_ID" \
  -H "Authorization: Bearer $IGDB_ACCESS_TOKEN" \
  --data 'fields name; limit 1;' \
  'https://api.igdb.com/v4/games')

if [ "$RESPONSE" = "200" ]; then
  curl -s https://vigilmon.online/heartbeat/igdb-heartbeat-url
fi

Schedule every 15 minutes. A 401 in this script means your IGDB token has expired and needs renewal via the Twitch OAuth endpoint.

Step 6: Monitor MobyGames API Connectivity

RomM can fall back to MobyGames for metadata when IGDB returns no results. Monitor it separately:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://api.mobygames.com/v1/games?api_key=your_key&title=test.
  3. Set Expected HTTP status to 200.
  4. Set Check interval to 10 minutes.
  5. Click Save.

If budget is a concern, use a HEAD monitor against https://api.mobygames.com as a connectivity probe instead.

Step 7: ROM Scan Job Heartbeat

RomM's background scanner discovers new ROM files, triggers metadata lookups, and updates the library. If the scheduler stalls, new ROMs appear in the filesystem but never show up in the UI.

Set up a heartbeat that fires after each scan job completes. If you access RomM's task API directly:

#!/bin/bash
# scan-job-monitor.sh — call after triggering a scan
# Trigger scan via RomM API
curl -sf -X POST https://romm.yourdomain.com/api/tasks/scan \
  -H "Authorization: Bearer $ROMM_TOKEN" >/dev/null 2>&1

# Wait for scan to complete (poll task status)
sleep 60

# Check if last scan succeeded
LAST_SCAN=$(curl -sf https://romm.yourdomain.com/api/tasks/last \
  -H "Authorization: Bearer $ROMM_TOKEN" | jq -r '.status')

if [ "$LAST_SCAN" = "finished" ]; then
  curl -s https://vigilmon.online/heartbeat/scan-heartbeat-url
fi
  1. In Vigilmon, click Add Monitor → Cron Heartbeat.
  2. Set expected interval to match your scan schedule (e.g. 60 minutes).
  3. Run the scan job script from cron at the same frequency.

Step 8: Monitor User Authentication

RomM uses JWT-based authentication. Test that the auth endpoint is working with a deliberate bad-credentials probe:

  1. Click Add Monitor → HTTP / HTTPS.
  2. Set URL to https://romm.yourdomain.com/api/login.
  3. Set Request method to POST.
  4. Set Request headers: Content-Type: application/json.
  5. Set Request body: {"username":"healthcheck","password":"invalid"}.
  6. Set Expected HTTP status to 401.

A 401 confirms the auth service is alive and correctly rejecting invalid credentials. A 500 or timeout means the JWT authentication layer has failed.

Step 9: SSL Certificate Expiry Alerts

Add SSL monitoring to your main RomM monitor:

  1. Open the RomM HTTP monitor created in Step 1.
  2. Enable Monitor SSL certificate.
  3. Set Alert when certificate expires in less than 21 days.
  4. Click Save.

Step 10: Configure Alert Channels

  1. Go to Alert Channels in Vigilmon and configure Slack, email, or webhook.
  2. Set Consecutive failures before alert to 2 on the web UI and API monitors.
  3. Set Consecutive failures to 1 on all heartbeat monitors (scan jobs, storage, database).
  4. For IGDB/MobyGames monitors, set Consecutive failures to 3 — external APIs have occasional transient failures.

Summary

| Monitor | Target | What It Catches | |---|---|---| | Web UI | https://romm.yourdomain.com | Frontend or proxy failure | | API heartbeat | /api/heartbeat | FastAPI backend crash | | PostgreSQL TCP | Port 5432 | Database server down | | PostgreSQL query | Heartbeat every 2 min | DB open but not serving queries | | ROM storage | Heartbeat every 5 min | Unmounted drive, read-only filesystem | | IGDB API | api.igdb.com | Token expiry, IGDB outage | | MobyGames API | api.mobygames.com | Alternative metadata source down | | ROM scan job | Heartbeat every 60 min | Scanner stall, missed schedule | | Auth endpoint | POST /api/login → 401 | JWT auth layer crash | | SSL certificate | Dashboard domain | Let's Encrypt renewal failure |

RomM turns decades of retro games into a beautifully organized library — Vigilmon makes sure that library stays accessible. With these monitors in place, you'll catch database failures, expired API credentials, and storage issues before your next gaming session instead of during it.

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