Running Uptimer

Commands, services, ports, the operations endpoint, state on disk and settings.

This is the operator reference for the 2.0 control plane: the commands it answers to, the settings it reads, the ports it serves, the paths it keeps state in, and what it no longer does. Coming from 1.8? Start with Moving from Uptimer 1.8 to 2.0.

The binary is uptimer. It is configured by environment variables and command flags. There is no configuration file.

Commands

Run the binary with no command and it serves: that is what a container does. An unknown command is refused rather than ignored.

Services

serve --services takes any of ui, api, grpc, judge, nats, cache, and eventbus as the alias for nats,cache. An unknown name is refused and the message lists the choices. A single box runs them all in one process; a fleet runs them apart against the same database, bus and cache.

Asking for grpc with UPTIMER__GRPC__PORT=0 is refused: a service that was asked for and cannot serve is not quietly dropped. An installation that runs no workers turns that port off and names no services, and the default set is then everything except the worker API.

A process that runs no database-backed service — nats, cache, eventbus — never opens the product’s database.

Ports

A port a process needs and cannot bind is a refusal to start that names the port. A process that logged the failure and carried on would look healthy while serving nothing.

Run the services apart and give each process its own operations port; that is how a fleet scrapes them separately.

Operations endpoint

Every long-running process — including worker — serves one operations listener:

Readiness goes non-OK when a selected service fails to start or its serving loop stops — the shell, the API, the worker API, the judge, the bus and the cache each report their own — so a process that has lost one of its jobs is taken out of a load balancer rather than left in it.

A process that serves the shell with OIDC sign-in also checks its provider’s discovery document: it must be reachable, be JSON, name exactly the configured issuer, and list the authorization, token and key endpoints. Otherwise /readyz answers 503 with oidc: …, because nobody can sign in. One answer holds for 15 seconds. /livez stays 200. The endpoint is on the operations listener and needs no sign-in.

A process asked for eventbus answers to that name as well as to nats and cache, because it is the name the deployment used.

The listener is not optional: serve and a worker daemon refuse to start without a port for it, because a process nothing can scrape or probe is one nobody can take out of a load balancer. UPTIMER__OPS__PORT moves it and UPTIMER__OPS__ADDR binds it to one interface. worker --once serves none: it asks, runs, reports and stops.

Metrics

route is the route pattern, not the path, so one route is one series.

The two totals exist so a quiet service can be told from a stopped one: a judge with no work and a judge that has died both report nothing otherwise.

A process running judge also removes delivery records older than 30 days, once an hour.

State that must survive a restart

Everything lives under one directory, so a deployment mounts one volume.

A relative path in any of those settings is read under the data directory, and an absolute one is used as given. A path typed on worker’s own --cert, --key or --ca flag is used as typed, so a worker started by hand from a directory of its own needs no data directory at all.

Restarting against the same directory reuses the database, the signing key — so sessions survive — the worker authority, the queued announcements, and a worker’s identity. None of them is recreated.

The worker authority is made on a first run, by the process that serves the worker API. Once certificates have been issued, a missing authority is a refusal to start instead: the trust every daemon holds is gone, and a new authority would refuse all of them while looking healthy. Back the directory up or keep issuing from a mounted volume.

PostgreSQL is the other supported backend: set UPTIMER__DB__DSN to a postgres://… URL, and the data directory then holds only the key, the authority and the queue.

Other settings

Shutdown

On SIGINT or SIGTERM an all-services process stops producers first, waits up to 15 seconds for the worker API to finish a report it is holding, and only then drains the event bus. A report in flight is not lost to a restart.

What 1.x had and this does not

These are deliberate removals, not oversights. Nothing in this reference or in any example uses them.