Quickstart
Run Uptimer 2.0.0-preview and one worker with Docker Compose, then watch a website until it opens an Incident.
Preview build. The image
2.0.0-rc15, pinned to its multiarch index digestsha256:945bd3a8fd42800445826df5d0968fd4c86d1d2a2e69f0fb41d897c66b0b0235(linux/amd64 and linux/arm64), is a 2.0 release candidate for the field test, not a final release.
This guide runs the control plane and one worker on one host. You sign in, add a Location, register the worker, issue its certificate and create a Resource. The worker checks it, and Uptimer opens an Incident when it fails. It takes about ten minutes.
You need Docker with the Compose plugin.
1. Start Uptimer
Save this as compose.yaml:
services:
uptimer:
image: ghcr.io/myuptime-info/uptimer:2.0.0-rc15@sha256:945bd3a8fd42800445826df5d0968fd4c86d1d2a2e69f0fb41d897c66b0b0235 # preview build
ports:
- "8080:8080" # the UI and the API
- "9090:9090" # /metrics, /livez, /readyz
environment:
UPTIMER__AUTH__DEV: "true" # trial sign-in; use OIDC in production
UPTIMER__GENERAL__SITE_URL: http://localhost:8080
UPTIMER__GRPC__HOSTS: uptimer,localhost # names the worker API's certificate is good for
volumes:
- uptimer-data:/data
worker:
image: ghcr.io/myuptime-info/uptimer:2.0.0-rc15@sha256:945bd3a8fd42800445826df5d0968fd4c86d1d2a2e69f0fb41d897c66b0b0235 # preview build
command: ["worker"]
restart: on-failure # waits until its certificate exists
environment:
UPTIMER__WORKER__GRPC_SERVER: uptimer:50051
UPTIMER__WORKER__CERT_FILE: /control/workers/edge-1/worker.pem
UPTIMER__WORKER__KEY_FILE: /control/workers/edge-1/worker-key.pem
UPTIMER__WORKER__CA_FILE: /control/workers/edge-1/worker-ca.pem
UPTIMER__OPS__PORT: "9091"
volumes:
- uptimer-data:/control:ro # one host only: reads the files worker-cert wrote
depends_on:
- uptimer
volumes:
uptimer-data:
Start it and wait until it is ready:
docker compose up -d
curl -s http://localhost:9090/readyz
/readyz answers ready when every service runs. The worker restarts until it has a certificate. That is expected: you issue it in step 3.
2. Sign in and add a Location
- Open
http://localhost:8080/ui/and choose Continue as Admin (development). Development sign-in is for this trial only; production uses OIDC. - Open Server → Locations → Add a location, for example
eu-central. A Location is a place checks run from.
Uptimer gives you a first workspace. To start over with an empty one (a fresh field round, say), open the workspace switcher at the top of the sidebar and choose Create workspace (from the release candidate after 2.0.0-rc2). Name it; you land on its settings as its owner, and the switcher takes you back to any other workspace. API v3 (POST /api/v3/workspaces), the Python SDK (client.create_workspace(name)) and MCP (create_workspace) do the same with a full API key.
3. Register the worker and issue its certificate
- Open Server → Workers → Register a worker. Name it
edge-1, choose the Location, and enter a new UUID as its Identity:uuidgen # or: cat /proc/sys/kernel/random/uuid - Issue its certificate on the control plane:This writes
docker compose exec uptimer /app/uptimer worker-cert --uid <the UUID> --out /data/workers/edge-1worker.pem,worker-key.pemandworker-ca.pem. The worker container reads them from the shared volume and connects on its next restart:docker compose logs worker | tail -2 # … msg="uptimer worker started" server=uptimer:50051 every=30s kinds=[http]
4. Watch a website
- Open Resources → Create Resource → Website.
- Enter a name and the URL to check. To see an Incident at once, use a page that answers 404, such as
https://example.com/this-page-does-not-exist, set Confirm after to0, and choose your Location. - Save. The worker runs the check at once:
docker compose logs worker | grep 'check ran' # … msg="check ran" assignment=… state=problem - Open the Resource. Its Rule reads problem, and the Resource links to its open Incident. The Incident page shows why it opened and why it is still a problem (see Read a problem).
From the release candidate after 2.0.0-rc2, Incidents in the sidebar lists the workspace’s open Incidents. From the release candidate after 2.0.0-rc7, it shows every open Incident: one somebody has acknowledged stays on the list, marked acknowledged with who and when, until it closes. Show narrows it to Not acknowledged (what still needs action) or Acknowledged, and Rule to one Rule; each keeps the other, and so does Older. Listing never changes an Incident or what is sent.
From the release candidate after 2.0.0-rc3, the Resource page says Why {rule} is open for each open Incident: its problem and the evidence it recorded when it opened, which later readings never change. Below it, Latest Signals shows each Signal as it stands now, with a Signal that never reported, went stale or says no_data named as such. The Resources list shows how long ago each Resource was created and how long its oldest open Incident has been open, and sorts by either.
From the release candidate after 2.0.0-rc7, Find on the Resources list searches by a Resource’s key, name or id; Clear shows every Resource again. Choose 25, 50 or 100 per page and move with Previous and Next: the search and sort stay as you page. Click a Resource’s name, key or id, on the list or on its page, to copy it.
From 2.0.0-rc9, Missing data narrows the list to Resources with a Signal that was never reported, has gone stale, or reported no_data; it is kept as you page.
Read a problem
From 2.0.0-rc12, the path from “something is wrong” to the evidence reads like this:
- Resources list. Each row shows the Template revision and up to three filled Template values (for example Server country nl · Provider hoster-b), apart from the Resource’s labels. Click a label to narrow the list to it; the active label shows as a chip with × that removes only the label and keeps your search, sort and page size.
- Resource page. The heading reads the Resource’s filled Template options, so you do not need Edit to tell which Resource this is. Every change sits in one Actions menu: Edit, Change settings, Rebind (pushed-data Resources) and Archive…. Delivery, Reminders and Maintenance are said once, in the heading. With an Incident open, Acknowledge sits next to See why it opened. A Rule in a problem state shows its condition checked again now, line by line.
- Timeline. The Resource page shows the latest changes; See the whole timeline opens every change, newest first, paged, narrowed by Day, Rule, Became and Only with an Incident. Every row names the Incident the change was recorded with, open or ended, or says No Incident. Nothing is linked by time alone.
- Incident page. It names the Rule and marks where the Incident is on pending → problem → closing → closed, from its own stored times; a step it never reached has no time. Incident condition is what the Rule last decided. Checked again now works the Rule’s condition out again from current readings, clause by clause for a composite Rule: each line holds, does not hold, cannot tell, or, for an input an “any one with data” group did not count, not counted: no usable data. A location-quorum Rule shows its verdict without clauses. Under it, each input says what it reads now and links to Its readings in the Observation log. Why it opened stays exactly as it was recorded; if the Rule was removed or replaced by a rebind, the page says there is no current condition to work out.
- Observation log. A failed report shows Rules it affected: each Rule change recorded against that report, with links to the decision and its Incident. A failed report with none says No recorded state change, and beside it which Rules read that Signal now, marked current configuration: Uptimer does not record Rules that read a report without changing, so it never claims one did.
A Resource that no Rule has judged yet reads not judged yet, on the list, on its page and for each such Rule: right after you create it, and after its first Observation until judging has run. That is neither healthy (ok) nor no data, which a Rule decides when its inputs give it nothing to go on. In API v3 such a Rule’s status is null.
5. Check a worker by hand
worker --once asks for the assignments, runs what is due, reports and stops. It exits non-zero when the control plane refuses it:
docker compose run --rm worker worker --once
6. Archive a Resource you no longer need
From the release candidate after 2.0.0-rc2, an editor or owner archives a Resource from the
UI: Archive on its row in Resources, or Actions → Archive… on its page. The next page names it and says
what archiving does; Cancel, keep it active changes nothing.
Archiving cannot be undone. The Resource leaves the Resource list, its checks stop,
Observations sent to it are refused, and it can no longer be edited or put in maintenance. Its
open Incidents close as archived, not as recovered, and nobody is notified. It keeps its key,
settings and history: Resources → Archived Resources lists it, and its page, timeline and
Incidents stay readable. There is no restore, and its key cannot be used again. A viewer
cannot archive. Archiving from the UI does exactly what the API’s
POST /api/v3/workspaces/{ws}/resources/{id or key}/archive does
(API v3).
Next
- From an API key to an Incident: the same path with the API and the Python SDK.
- Run it for real: one volume, PostgreSQL, OIDC, a fleet of workers.
- Add a notification: Settings → Destinations sends Incidents to Slack or a webhook.