Uptimer v2.0.0-preview documentation — it describes the release candidate, and v1.8.0 remains the current release. Commands here pull the preview image :2.0.0-rc15@sha256:945bd3a8fd42800445826df5d0968fd4c86d1d2a2e69f0fb41d897c66b0b0235. The Python SDK for this preview is a local wheel, not a PyPI release. Go to the current release (v1.8.0) →
Getting started › Quickstart

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 digest sha256: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

  1. Open http://localhost:8080/ui/ and choose Continue as Admin (development). Development sign-in is for this trial only; production uses OIDC.
  2. 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

  1. 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
    
  2. Issue its certificate on the control plane:
    docker compose exec uptimer /app/uptimer worker-cert --uid <the UUID> --out /data/workers/edge-1
    
    This writes worker.pem, worker-key.pem and worker-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

  1. Open Resources → Create Resource → Website.
  2. 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 to 0, and choose your Location.
  3. Save. The worker runs the check at once:
    docker compose logs worker | grep 'check ran'
    # … msg="check ran" assignment=… state=problem
    
  4. 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:

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