1 — Getting started

This is a self-hosted status service: it probes your services every minute the way a user needs them (content assertions, and where a cheap deep probe exists, by exercising the user path), renders an honest public board, feeds RSS/Atom + email subscriptions, and gives you a runtime admin interface. Cloudflare Workers share the job: the status worker (the prober + the page + the admin) plus one optional relay worker PER DECLARED VANTAGE (each probing from its own scheduling location — this estate declares two, relay-1 and relay-2).

The promises (the honest postures)

These are the product; every feature defers to them:

• A green means the user's path works — never that a shell endpoint answered. Every probe carries a content assertion.
• The verdict is a worst-of across vantages. A failure from ANY reporting vantage marks the service; a silent vantage reads UNKNOWN, never green, and the page names the gap.
• Degraded/down carries the last-good timestamp. No data renders as no data; a frozen page says so.
• Never rounded up. Percentages truncate; the SLO block says "missing" in plain view.
• Incidents are human prose. Automation opens DRAFTS (never rendered, never mailed); humans publish — through the admin or the git-PR path.
• Fail-closed everywhere. Unset secrets close surfaces honestly (404/503), never pretend.

The ten-minute first instance

1. Declare your instance in config/status.yaml: the site identity (name, base URL, logo pair, links, optionally fonts and theme colors), the display groups, every service you probe with its content assertion, the vantages, and optionally the mail block. The full field contract: the configuration reference.

2. Build and verify locally:

   npm install
   npm run dev           # wrangler dev: the board at localhost:8787
   npm run probe:live    # one real round against your real services
   

   probe:live is the honest pre-deploy gate: it exercises the real registry against the real estate and exits nonzero on any failed assertion.

3. Deploy: copy wrangler.example.toml to wrangler.toml, name your worker, create + wire your KV namespace, then npm run deploy. Running a relay vantage? Edit each wrangler.relay*.toml — its STATUS_REPORT_URL and STATUS_VANTAGE_ID must point at YOUR instance and match a vantage id your YAML declares (the templates ship Ribose's values) — then npm run deploy:relay / npm run deploy:relay2 and set the shared secret on both sides: npx wrangler secret put STATUS_RELAY_TOKEN and the same again with --config wrangler.relay.toml (and wrangler.relay2.toml). Attach your domain with bash scripts/attach-custom-domain.sh (it derives the hostname, zone, and worker name from your config; export CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_API_TOKEN first, and STATUS_SERVICE if your worker lives under another name).

4. Operate: set the secrets (OPS_TOKEN for the admin; the relay token if you run the relay; the mail provider key if you take email subscriptions live), sign in at /admin, and you are operating. The next chapters cover the page, the admin, and operations.

Whitelabel — running this as another org, under another brand — is the same five steps with your own theme; see the whitelabel runbook.