polystatus

polystatus is a standalone, YAML-configured uptime monitoring service with persistent history (SQLite), an HTTP API, and a 3D “status home” UI.

Quickstart (local)

1. Copy the example config:

Copy-Item .\config.example.yaml .\config.yaml

2. Run the server (this is a long-running process; leave it running until you press Ctrl+C):

go run .\cmd\server -config .\config.yaml

3. Open the UI:

• http://localhost:8080

If you want to run the web dev server instead (hot reload UI):

cd web
npm install
npm run dev

The web dev server proxies API calls to the Go server (see web/vite.config.ts).

Quickstart (Docker)

Docker expects the config file mounted at /config.yaml (the container default) and a persistent /data volume for SQLite.

The container runs polystatus as an unprivileged user (uid 10001) and has a built-in health check (docker ps shows healthy). On start it takes ownership of /data, so volumes from older, root-run images keep working.

1. Copy the Docker-oriented example config:

Copy-Item .\config.docker.example.yaml .\config.yaml

2. Start the container:

docker compose up -d

Docker compose variants

• Dev (build locally):

docker compose -f .\docker-compose.dev.yml up --build

• Production (pull from Docker Hub):
  • latest is the newest release tag (vX.Y.Z); dev tracks the main branch
  • Set the image in docker-compose.yml to your Docker Hub repo/tag if needed

docker compose up -d

Configuration

• Full reference (all options, defaults, examples): CONFIGURATION.md
• Upgrading: a config from an older version keeps working, and -migrate-config rewrites it with the current names. The database is upgraded on start. See "Upgrading from an older version" in CONFIGURATION.md.

HTTP API

• GET /api/v1/status: everything the UI shows. The ui settings (durations in milliseconds, such as refresh_interval_ms), plus checks[] with:
  • id, name, group, importance, state, link
  • origin: scheme://host the check points at
  • latency_ms: omitted for heartbeat checks
  • uptime_pct: share of the history window the check was available
  • ticks: "up", "degraded", "down" or null, oldest first
  • last_error
  • updated_at: ms; null until the check first runs
• GET /api/v1/checks: id, name, group and state of every check.
• GET /api/v1/checks/{id}/ticks?window=24h&bin=1m: a check's history.
• GET /api/v1/checks/{id}/favicon: the check's site favicon, fetched and cached by polystatus.
• GET /api/v1/summary: the overall state, which is the worst state among all checks.
• GET /api/v1/events: Server-Sent Events. Each state_change event carries check_id, prev_state, state and ts.
• POST or GET /api/v1/push/{id}/{token}: pushes to a heartbeat check.
• GET /healthz: liveness.

With public_mode: false, everything except /healthz and push URLs needs the access token.