tutorial

Monitoring Roadie with Vigilmon: Hosted Backstage Health, Catalog API, Plugin Availability & SSL Certificates

How to monitor Roadie (hosted Backstage developer portal) with Vigilmon — portal health checks, software catalog API availability, plugin endpoint monitoring, TechDocs accessibility, and SSL certificate monitoring.

Roadie is the managed hosting platform for Backstage, the open-source developer portal from Spotify, eliminating the operational burden of self-hosting Backstage by providing a fully managed, multi-tenant service with plugin management, RBAC, and enterprise SSO out of the box. When the Roadie portal goes down or the software catalog API becomes unavailable, engineering teams lose their internal developer portal — the single source of truth for service ownership, documentation, APIs, and runbooks. Vigilmon gives you external visibility into Roadie portal availability, catalog API health, plugin endpoints, TechDocs accessibility, and SSL certificates so platform teams get ahead of developer portal outages.

What You'll Build

  • An HTTP monitor on the Roadie portal health endpoint
  • An HTTP monitor for the Backstage software catalog API
  • An HTTP monitor verifying TechDocs search and documentation availability
  • SSL certificate monitoring for your Roadie subdomain
  • An alerting runbook for Roadie failure modes

Prerequisites

  • An active Roadie account with a provisioned tenant (e.g., yourcompany.roadie.so)
  • At least one software catalog entity registered in Roadie
  • A free account at vigilmon.online

Step 1: Verify the Roadie Portal Availability

Your Roadie portal is accessible at a tenant-specific subdomain: https://<your-org>.roadie.so. Confirm the portal loads correctly:

curl -I https://yourcompany.roadie.so

A healthy Roadie portal returns 200 OK. The main portal URL is the primary signal of overall portal health — if it returns a non-200 or times out, all developers in your organization lose access to their developer portal.

Step 2: Create a Vigilmon HTTP Monitor for the Roadie Portal

  1. Log in to Vigilmon → Add Monitor → HTTP.
  2. URL: https://yourcompany.roadie.so (replace yourcompany with your Roadie tenant name).
  3. Check interval: 60 seconds.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: Roadie (or another string from your portal's HTML that confirms the page loaded).
  7. Label: Roadie Developer Portal.
  8. Click Save.

Set alerts after 1 consecutive failure — a Roadie portal outage removes the single source of truth for every service, API, and runbook in your organization.

Step 3: Monitor the Backstage Software Catalog API

Roadie's most critical backend service is the Backstage software catalog API, which serves entity lookups, ownership data, and dependency graphs. The catalog API is used by the portal UI, CI/CD integrations, and any internal tooling that calls Backstage APIs. Monitor the catalog health endpoint:

curl https://yourcompany.roadie.so/api/catalog/entities?limit=1

With a valid Roadie token, this returns a JSON array of catalog entities. For unauthenticated availability checks, use the catalog ping endpoint:

  1. Add Monitor → HTTP.
  2. URL: https://yourcompany.roadie.so/api/catalog/entities?limit=1.
  3. Check interval: 2 minutes.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: kind (present in every catalog entity JSON response).
  7. Label: Roadie Catalog API.
  8. Click Save.

Authentication note: If your Roadie tenant requires authentication on all API routes, configure Vigilmon's HTTP monitor with a Bearer token header using a service account token from Roadie settings. Alternatively, use a dedicated unauthenticated health path if available.

Step 4: Monitor TechDocs Availability

TechDocs is Roadie's managed documentation site that renders Markdown docs from your repositories. When TechDocs is unavailable, engineers lose access to service runbooks, architecture documents, and API references during incidents — exactly when they need them most:

  1. Add Monitor → HTTP.
  2. URL: https://yourcompany.roadie.so/docs (or the URL of a critical TechDocs entry point).
  3. Check interval: 5 minutes.
  4. Response timeout: 15 seconds.
  5. Expected status: 200.
  6. Keyword: Docs (or a known string from your TechDocs index page).
  7. Label: Roadie TechDocs.
  8. Click Save.

Step 5: Monitor Third-Party Plugin Endpoints

Roadie integrates with external services (GitHub, PagerDuty, Datadog, Jira, etc.) through Backstage plugins. Each plugin proxies requests from the Roadie portal to external APIs. Monitor the availability of your most critical plugin backend targets:

GitHub integration (required for catalog entity discovery):

  1. Add Monitor → TCP.
  2. Host: api.github.com.
  3. Port: 443.
  4. Check interval: 5 minutes.
  5. Label: GitHub API (Roadie integration).
  6. Click Save.

PagerDuty integration (if using the Roadie PagerDuty plugin):

  1. Add Monitor → TCP.
  2. Host: api.pagerduty.com.
  3. Port: 443.
  4. Check interval: 5 minutes.
  5. Label: PagerDuty API (Roadie integration).
  6. Click Save.

When GitHub API is unreachable, Roadie's catalog ingestion from GitHub repositories stalls and entities go stale — new services, deleted components, and ownership changes stop appearing in the portal.

Step 6: Monitor the Roadie OAuth / SSO Endpoint

Roadie uses OAuth 2.0 / OIDC for authentication. Engineers who have not recently logged in are redirected to an OAuth flow. If the OAuth provider is down, no one can log into Roadie:

  1. Add Monitor → HTTP.
  2. URL: https://yourcompany.roadie.so/api/auth/github/start (or okta, google, depending on your Roadie SSO provider).
  3. Check interval: 5 minutes.
  4. Response timeout: 10 seconds.
  5. Expected status: 302 (redirect to OAuth provider — a 302 means Roadie's auth service is healthy even though you're not following the redirect).
  6. Label: Roadie OAuth Start.
  7. Click Save.

Step 7: Monitor SSL Certificates

Roadie portal TLS is managed by Roadie for the *.roadie.so domain. However, if your organization uses a custom domain for Roadie, you own that certificate. Expired certificates lock all developers out:

  1. Add Monitor → SSL Certificate.
  2. Domain: yourcompany.roadie.so (or your custom Roadie domain).
  3. Alert when expiry is within: 30 days.
  4. Alert again at: 14 days, 7 days, 3 days, 1 day.
  5. Click Save.

Also monitor your OIDC/SSO provider's certificate if you control it:

  1. Add Monitor → SSL Certificate.
  2. Domain: auth.yourcompany.com (your IdP domain).
  3. Alert when expiry is within: 30 days.
  4. Click Save.

Step 8: Configure Alerting

In Vigilmon under Settings → Notifications, configure your alert channels:

| Monitor | Trigger | Action | |---|---|---| | Roadie portal | Non-200 or keyword missing | Check Roadie status page; notify platform team | | Catalog API | Non-200 or kind keyword missing | Catalog backend down; check Roadie status page | | TechDocs | Non-200 or keyword missing | Docs unavailable; check Roadie status page | | GitHub API TCP | Connection refused | GitHub outage; catalog ingestion stalls | | PagerDuty API TCP | Connection refused | On-call plugin broken; verify incident escalation paths | | Roadie OAuth | Not 302 | SSO broken; new logins impossible | | SSL certificate | < 30 days | Renew; update DNS / Roadie custom domain config |

Common Roadie Failure Modes and What Vigilmon Catches

| Scenario | Vigilmon monitor | |---|---| | Roadie SaaS outage | Portal HTTP monitor fires within 60 s | | Backstage catalog API down | Catalog API monitor fires within 2 min | | TechDocs backend unavailable | TechDocs monitor fires | | GitHub API outage (catalog ingestion stalls) | GitHub TCP monitor fires | | OAuth provider down (logins blocked) | OAuth start monitor returns non-302 | | TLS certificate expired (all access blocked) | SSL monitor alerts at 30-day threshold | | PagerDuty plugin proxy failing | PagerDuty TCP monitor fires | | Roadie custom domain DNS failure | Portal HTTP monitor times out |

Roadie's managed Backstage service means platform teams trade operational complexity for a dependency on Roadie's infrastructure — and when that infrastructure has an incident, the entire engineering organization simultaneously loses their developer portal, including the service catalog, TechDocs, and on-call runbooks that would normally guide incident response. Vigilmon's layered monitoring of the Roadie portal, catalog API, TechDocs, plugin dependencies, OAuth provider, and SSL certificates ensures that platform teams learn about developer portal outages from their monitoring system, not from developers reporting blocked workflows.

Start monitoring Roadie in under 5 minutes — 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