Documentation

Everything you need to deploy, configure, and operate Relay — self-hosted, enterprise-grade uptime monitoring with a built-in public status page.

Quick Start

One-liner (no config file)

docker run -d \
  --name relay \
  --restart unless-stopped \
  -p 8080:8080 \
  -v relay-data:/data \
  -e RELAY_SECRET=$(openssl rand -hex 16) \
  -e RELAY_SITE_NAME="Acme Status" \
  -e RELAY_SITE_URL="https://status.example.com" \
  -e RELAY_ADMIN_PASS=yourpassword \
  ghcr.io/rohzzn/relay

• Status page: http://localhost:8080
• Admin dashboard: http://localhost:8080/admin (login: admin / your password)
• REST API: http://localhost:8080/api/v1/monitors

Docker Compose + Caddy (auto-TLS, recommended)

git clone https://github.com/rohzzn/relay
cd relay
cp .env.example .env
# Edit .env — set RELAY_SECRET, RELAY_ADMIN_PASS, RELAY_SITE_NAME, RELAY_SITE_URL
# Edit Caddyfile — replace status.example.com with your domain

docker compose up -d

Caddy handles Let's Encrypt automatically. No certificate configuration needed.

Build from source

git clone https://github.com/rohzzn/relay
cd relay
go build -o relay ./cmd/relay

RELAY_SECRET=secret RELAY_ADMIN_PASS=admin ./relay

Requires Go 1.22+. No other dependencies.

Configuration

All settings are environment variables. Only RELAY_SECRET and RELAY_ADMIN_PASS are required:

Monitor Types

Per-monitor options

These fields are available on the monitor form and stored as JSON in the config column:

Pause & Test Now

Every monitor card has two quick actions:

• Pause / Resume — stops checks immediately without deleting the monitor. The monitor shows as paused on the dashboard and is hidden from the public status page.
• Test Now — fires a single probe immediately and shows the result inline. Also available as a button on the monitor edit form. Useful for verifying a new monitor before relying on it.

Heartbeat Monitors

A heartbeat monitor expects your cron job to POST to Relay on each successful run. If the ping stops arriving within the check interval, Relay opens an incident.

After creating a heartbeat monitor, the dashboard shows the exact endpoint to call:

POST https://status.example.com/ping/{monitor-id}

Example crontab entry:

*/5 * * * * /path/to/job && curl -sS -X POST https://status.example.com/ping/YOUR_MONITOR_ID

Monitor Groups

Assign a Group / Category to each monitor on its form (e.g. API, Database, CDN). Monitors with the same group name are displayed together as a labelled section on both the admin dashboard and the public status page — identical to enterprise Statuspage.io.

• Monitors with no group are shown under Ungrouped on the dashboard and Services on the status page.
• Groups appear in the order their first monitor was created.
• You can rename a group by editing all monitors in it.

Alert Channels

Configure channels in Admin → Alert Channels. Each channel has a Send Test button to fire a dummy alert and verify the connection before relying on it.

Alerts have a built-in 10-minute cooldown per monitor to prevent alert storms. Recovery ("back up") notifications always send immediately, bypassing the cooldown.

Per-monitor routing

By default, all configured channels fire for every monitor. On the monitor create/edit form, check specific channels under Alert Channels to route only those — for example, database alerts to PagerDuty and API alerts to Slack. Leave all boxes unchecked to use all channels (the default).

Maintenance Windows

Schedule maintenance windows in Admin → Maintenance to suppress alerts during planned downtime such as deployments, migrations, or infrastructure changes.

• During an active window, monitors continue running and check results are recorded — but no incidents are auto-created and no alert channels fire.
• Windows can target all monitors or a specific monitor.
• The dashboard and status page continue to reflect real monitor status — the window only suppresses alerting.
• Completed, upcoming, and active windows are listed with their time range and scope.

Team & RBAC

Invite team members in Admin → Team. Each user gets a role that controls what they can do:

Team member passwords are hashed with bcrypt. The root admin account (RELAY_ADMIN_USER / RELAY_ADMIN_PASS) always has full access and cannot be removed through the UI. Role changes take effect on the user's next page load.

REST API

Relay exposes a REST API at /api/v1/. Use it for CI/CD pipelines, Infrastructure-as-Code, Grafana datasources, or any automation.

Authentication

Create API keys in Admin → Settings. Each key has a role (Admin, Editor, or Viewer) that controls what it can do. Pass the key as a Bearer token:

curl -H "Authorization: Bearer relay_..." \
     https://status.example.com/api/v1/monitors

Admin session cookies also authenticate API requests, so the API works from the browser too.

Endpoints

Example: create a monitor

curl -X POST \
  -H "Authorization: Bearer relay_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"Payments API","type":"http","target":"https://pay.example.com/health","interval_s":60,"group":"API"}' \
  https://status.example.com/api/v1/monitors

Example: pull latency metrics

curl -H "Authorization: Bearer relay_..." \
  "https://status.example.com/api/v1/monitors/MONITOR_ID/metrics?hours=24"

Returns an array of {"bucket": unix_ts, "avg_ms": float, "check_count": int} points bucketed at 15-minute intervals for ≤24h or 1-hour intervals for longer windows.

Audit Log

Every admin action is recorded in the audit log, accessible at Admin → Audit Log. Each entry captures:

• Actor — the username (or api for API key actions)
• Action — what was done: create, update, delete, pause, resume, resolve, update_role
• Entity type — monitor, incident, channel, user, api_key, maintenance_window
• Detail — the name or relevant identifier of the entity
• Timestamp — when the action happened

The log is append-only and paginated at 50 entries per page. It cannot be cleared through the UI.

Architecture

relay/
├── cmd/relay/          Entry point, graceful shutdown, healthcheck subcommand
├── internal/
│   ├── config/         Environment-based configuration (env vars only)
│   ├── db/             SQLite (WAL mode), all queries — no ORM
│   ├── check/          HTTP · TCP · TLS · DNS · Heartbeat checkers
│   ├── scheduler/      Per-monitor goroutines with semaphore concurrency pool
│   ├── state/          FSM: up/degraded/down, auto incident open/close
│   ├── alert/          Cooldown-aware dispatcher with per-monitor channel routing
│   ├── notify/         Slack · SMTP · Webhook · PagerDuty · OpsGenie adapters
│   └── server/         HTTP handlers · WebSocket hub · HMAC session auth · REST API
└── web/
    ├── templates/       html/template pages — embedded in the binary
    └── static/          CSS (dark mode) + JS — embedded in the binary

Why Go?

Single static binary, goroutine-per-monitor scheduler, ~15 MB Docker image. Uptime Kuma is 200 MB and people notice.

Why SQLite WAL?

Zero ops. Back up with cp relay.db relay.db.bak. Handles dozens of concurrent readers with WAL mode. No Postgres to run, no connection pool to tune.

Why HTMX?

The live dashboard has real-time updates with zero client-side framework. No React, no build step — the dashboard loads in under 300ms on a Raspberry Pi and the entire admin UI weighs less than 50 KB.

Database schema

Key tables and their purpose:

Roadmap

• ✓ HTTP, TCP, TLS, DNS, Heartbeat monitors
• ✓ Live dashboard via WebSocket with sparklines
• ✓ 90-day uptime bars
• ✓ Grouped monitor sections
• ✓ Pause / resume monitors
• ✓ Test Now button
• ✓ Incident management with timeline updates
• ✓ Public incident history page
• ✓ Email subscriber list with confirmation
• ✓ Alert channels — Slack, webhook, SMTP email
• ✓ PagerDuty and OpsGenie integrations
• ✓ Per-monitor alert channel routing
• ✓ Send Test button per channel
• ✓ Maintenance windows
• ✓ Team RBAC (Admin / Editor / Viewer)
• ✓ REST API v1 with scoped API keys
• ✓ Audit log
• ✓ Dark mode
• ✓ Custom 404/500 pages
• ✓ Docker healthcheck subcommand
• v2: relay-probe — lightweight agent binary for multi-region monitoring
• v2: Response time history graphs in the dashboard
• v3: On-call schedule with rotating recipients
• v3: SSO (OIDC)

Contributing

1. Fork the repo
2. go run ./cmd/relay — starts with live template reloading
3. Templates are in web/templates/, styles in web/static/style.css
4. Open a PR — all contributions welcome

Code style: Standard gofmt. No ORM — queries live in internal/db/db.go as plain SQL. No external router — Go 1.22 stdlib mux only. No frontend build step.

License

MIT — see LICENSE on GitHub.

Relay is not affiliated with Uptime Kuma or Statuspage.io.