Self-hosted internet speed monitor. Runs @cloudflare/speedtest on a configurable schedule, stores every measurement in SQLite, and serves a dashboard with live updates over WebSocket.

Stack

• Runtime: Bun 1.x
• Package manager: Bun 1.3
• Framework: Next.js 16 (App Router) + TypeScript 6 + Biome 2 + Tailwind v4
• Custom server (server.ts): hosts Next.js and a ws WebSocket endpoint on the same port
• Scheduler: node-cron 4.x, reprogrammable at runtime from the UI
• DB: Drizzle ORM 0.45 + bun:sqlite (built-in)
• Measurement engine: @cloudflare/speedtest (HTTP-only, no browser)
• Tests: Bun native (bun test)
• Runtime image: oven/bun:1-slim

Run with Docker

docker compose up -d --build
open http://localhost:3000

Configuration:

Change the interval at any time via the UI (/settings) - it is persisted in SQLite and takes effect immediately without a restart.

Alerts

speedtest-monitor can notify you when your connection degrades or fails, and again when it recovers. Alerts are fully opt-in - nothing fires until you enable them and set at least one threshold.

Configure destinations (env vars)

All destinations are optional. A destination is available iff its required env vars are set.

Configure rules (UI)

In /settings, toggle "Enable alerts", set any subset of thresholds (download, upload, latency, bufferbloat, failure streak), and enable the destinations you want. Each destination has a "Send test" button to verify wiring without waiting for a real incident.

Semantics

• Fire on transition only. Once a condition enters ALERTING it will not re-fire until it first recovers. No spam during prolonged outages.
• Per-condition state. Download dropping while latency is fine -> one alert. Latency spiking later -> a second independent alert.
• Failure streak. Counts consecutive measurements with status error/timeout ending at the current one - useful when the connection actually goes down.
• Secrets stay in env. Destination credentials are never persisted to the SQLite DB and never returned by /api/alerts/rules.

Authentication

speedtest-monitor requires authentication for all routes. Two roles exist:

• admin - full access, can manage users, change settings, configure alerts, trigger manual measurements
• viewer - read-only access: dashboard, history, settings in read-only mode

Required environment

AUTH_SECRET=<run: openssl rand -base64 32>
BETTER_AUTH_URL=https://speedtest.example.com   # required when served behind a reverse proxy

Missing AUTH_SECRET is a fatal boot error. BETTER_AUTH_URL defaults to http://localhost:${PORT} when unset, which is fine for local dev but must be overridden in production so callbacks and OIDC redirects work.

First run: create the first admin

Pick one of the following three paths. They are independent; the most recent write wins.

Path A: env seed (recommended for docker-compose)

SPEEDTEST_ADMIN_EMAIL=admin@example.com
SPEEDTEST_ADMIN_PASSWORD=<at least 10 chars>

The seed runs at every boot and is idempotent: the admin is created if absent, promoted to admin if demoted, and rehashed if the password env var has changed.

Path B: setup wizard

Visit /setup on first boot. The page is only accessible while no user exists. You can create your admin account from the form.

Path C: OIDC admin claim

Set SPEEDTEST_OIDC_ADMIN_EMAIL=you@example.com in addition to the OIDC env vars below. On first OIDC sign-in with that email, the account is auto-promoted to admin.

OIDC single sign-on (optional)

SPEEDTEST_OIDC_ISSUER=https://auth.example.com
SPEEDTEST_OIDC_CLIENT_ID=speedtest
SPEEDTEST_OIDC_CLIENT_SECRET=...
SPEEDTEST_OIDC_DISPLAY_NAME=SSO           # label on the sign-in button
SPEEDTEST_OIDC_ADMIN_EMAIL=you@example.com
SPEEDTEST_OIDC_ALLOW_NEW_USERS=true       # "false" = only admin-created users may sign in via OIDC

Tested with Authelia, Authentik, and Keycloak (any OIDC-compliant provider should work).

User management

Admins manage users from /settings under the "Users" card. Add a user with an initial password (no email invite in v1). Admins can change roles, reset passwords, and delete users. The last remaining admin cannot be demoted or deleted.

Upgrading from a pre-auth version

1. Set AUTH_SECRET in your environment before starting the upgraded container.
2. Pick a bootstrap path (A, B, or C above).
3. Scripts and cURL commands that previously called /api/* anonymously will now receive 401 Unauthorized. Add an authenticated session cookie or migrate to the session-aware clients.

Upgrading from the next-auth release

The auth stack moved from next-auth v5 beta to Better Auth. Same env vars, but:

1. Set BETTER_AUTH_URL to your public origin (AUTH_TRUST_HOST is no longer used).
2. On first boot, the existing users table is copied into the new user/account tables. Argon2id password hashes verify without re-hashing.
3. Sessions are now stored in the database (no longer JWT), so every user must sign in again after the upgrade.
4. User ids changed from auto-increment integers to UUIDs. Any external script that hard-coded a numeric user id needs to be updated.

Upgrading the measurement engine

The 0.2+ release swaps the measurement backend from fast.com (via the fast-cli + Chromium browser) to Cloudflare Speed Test (HTTP only). On first boot after the upgrade:

• Three new nullable columns (jitter_ms, packet_loss_pct, user_isp) are added to the measurements table. Historical rows keep them null - the data was never captured.
• Post-upgrade rows record the Cloudflare edge code (e.g. CDG) in server_locations instead of Netflix Fast's location strings (e.g. Paris, FR | Saint Denis, FR).
• Absolute speed numbers may differ slightly vs. pre-upgrade runs because the CDN behind the test is different. The trend is still directly comparable.
• The container image shrinks by roughly 700 MB; no Chromium, no fonts-liberation, no sandbox requirement.

Development

bun install
bun run db:generate        # generate drizzle migrations
bun run dev                # bun server.ts -> http://localhost:3003
bun test                   # bun native unit tests
bun run lint               # biome check .
bun run tsc                # tsc --noEmit
bun run build              # drizzle generate + fetch releases + build email templates + next build

End-to-end check

# trigger one measurement (~20s)
curl -X POST http://localhost:3003/api/measurements/run

# read history
curl 'http://localhost:3003/api/measurements?range=24h' | jq

# tail the WebSocket stream
websocat ws://localhost:3003/ws

# change interval (live)
curl -X PATCH http://localhost:3003/api/settings \
  -H 'content-type: application/json' \
  -d '{"intervalMinutes":5}'

API

All routes require an authenticated session (cookie or OIDC). Mutating routes require the admin role.

Tests

Unit tests live next to the code they cover (lib/**/*.test.ts, components/**/*.test.ts). Run with:

bun test

Covered areas: cron expression generation, measurement DTO mapping, range and pagination query parsing, alert evaluation and per-condition state machine, alert dispatch and formatting, MJML email rendering, every destination adapter (webhook, ntfy, Discord, Slack, SMTP), auth bootstrap and config, password hashing, OIDC providers, and user management.

Reverse proxy

The WebSocket lives on /ws. Make sure your proxy forwards the Upgrade header:

location /ws {
  proxy_pass http://speedtest:3000;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
}