Skip to content

Install the components you operate

Use urthctl on the machine where you manage resources. Install urth-worker in each network location from which you need measurements. Install the API and web interface only if you operate your own control plane.

Override the control-plane address

These guides assume that the control plane runs at https://urth.example.org and that urthctl and urth-worker are configured to use it by default. You can omit the address from the normal examples. This is a configuration assumption for these guides; an unconfigured source build can have a different default.

For another deployment, save a separate CLI profile during login:

urthctl --profile=other auth login --api-server-address=https://other.example.org
urthctl --profile=other get scenarios

The profile retains its endpoint. Select that profile for later commands. A profile's credential cannot be sent to a different endpoint by overriding its address after login. Authenticate a separate profile instead.

For a Worker, set the override in its service arguments:

install -d -m 700 "$HOME/.local/state/urth-worker/work"
urth-worker --working-directory="$HOME/.local/state/urth-worker/work" \
  --token-file /secure/path/runner-token \
  --client.api-server-address=https://other.example.org

The CLI flag is --api-server-address. The Worker flag is --client.api-server-address. Broker addresses returned by the API take precedence over --nats.url.

Use a matching release set

The release packaging defines archives for the Linux API and Worker, and for urthctl on Linux and macOS, for amd64 and arm64. It also defines Debian packages, snaps, and container images. Check the assets actually present in your selected release. Availability of each channel and asset depends on the selected release.

Download an archive and checksums.txt from the same release. Compare its SHA-256 digest with the listed digest. Extract the executable to a directory on your PATH. Then check the command:

urthctl --help
urth-worker --help

The archive names are urthctl_<version>_<os>_<arch>.tar.gz and urth-worker_<version>_linux_<arch>.tar.gz. Use darwin for macOS. Use the version string exactly as the release names it.

The native Worker container and Worker snap support native probes, including HTTP, TCP, DNS, ICMP, gRPC, REST, and HAR replay. They do not include browser probe support. ICMP also requires suitable host permissions. For browser scripts, follow Set up browser probes.

When using a container, provide a private token file and a persistent writable configuration volume. Give each installation its own volume. A replaced container must retain its installation key. Check the selected release's container guide for image and mount details.

Set up browser probes on a Linux host

Use a host Worker build that includes Puppeteer support. The native container and snap cannot acquire this capability by installing Node.js. Run the setup as the same operating-system user that runs the Worker. Start from the source checkout for your selected Urth release.

Install Node.js and npm versions compatible with that release's Puppeteer package. Copy the release's locked dependency files to the Worker directory:

install -d -m 700 "$HOME/.local/state/urth-worker/work"
cp worker/package.json worker/package-lock.json "$HOME/.local/state/urth-worker/work/"
cd "$HOME/.local/state/urth-worker/work"
npm ci
npx puppeteer browsers install chrome

Installation needs registry and browser-download access. Install the browser's host libraries for your Linux distribution. Use Puppeteer's system requirements and Linux troubleshooting instructions for the package version in your release. Do not assume that the current upstream requirements also apply to an older locked version.

Save this as browser-smoke.js in that working directory:

const puppeteer = require('puppeteer');
(async () => {
  const browser = await puppeteer.launch({ headless: true });
  try {
    const page = await browser.newPage();
    await page.goto('data:text/html,<title>Urth smoke test</title>');
    if (await page.title() !== 'Urth smoke test') throw new Error('Unexpected title');
    console.log('Browser smoke test passed');
  } finally {
    await browser.close();
  }
})().catch(error => { console.error(error); process.exitCode = 1; });

node browser-smoke.js
urthctl run -f browser-smoke.js --puppeteer.headless \
  --runner.working-directory="$PWD" --runner.timeout=30s

Expect Browser smoke test passed and a successful final probe result. The first command checks the installed browser. The second checks Urth's execution path. Resolve missing libraries, browser-cache permissions, or sandbox configuration before enrolling the Worker. Keep the browser sandbox enabled. The service user must retain access to the downloaded browser and packages.

Start the Worker with --working-directory set to this directory. Confirm that it advertises Puppeteer support and that its Runner permits puppeteer jobs. This smoke test does not check connectivity to your service; test the actual workflow next.

Build from source

From an accessible Urth source checkout, use the Go toolchain required by go.mod:

go build -o urthctl ./cmd/urthctl
go build -o urth-worker ./cmd/nats-worker

The source directory is named cmd/nats-worker; the packaged executable is named urth-worker. The CLI and Worker must be compatible with your API release. Follow Connect probers after installation.

Start a local development stack

Use a fresh PostgreSQL 18 database and a fresh NATS JetStream store. Earlier PostgreSQL versions and migration of existing Urth resources are unsupported. SQLite is not a supported alternative, even though an old API default names it.

The source quick start requires Go, Podman, jq, and Node.js/npm. The website uses a private GitHub Packages dependency. Configure package read access outside the repository before installing it. Use a separate terminal for each process:

make run-postgres-podman

make run-nats-podman

make run-api-server

In a fourth terminal:

cd website
npm install
npm run dev

The default development UI is http://localhost:3001. The API is http://localhost:8080. The development Makefile bootstraps admin@urth.example with password urth-dev-password. Use these credentials only in an isolated development environment. The container targets bind host ports; restrict access to the development host.

Use the quick start with this login command:

urthctl auth login --api-server-address=http://localhost:8080

For a Worker on the same host, replace the HTTPS Worker command with:

install -d -m 700 "$HOME/.local/state/urth-worker/work"
./urth-worker --working-directory="$HOME/.local/state/urth-worker/work" \
  --token-file /secure/path/runner-token \
  --client.api-server-address=http://localhost:8080 \
  --allow-insecure-api --nats.allow-insecure

The insecure flags permit loopback development only. Remote deployments require an HTTPS API and authenticated NATS over TLS. Do not use development bootstrap credentials, ephemeral stores, or these Makefile targets as a production setup. Security and release validation remain prerequisites for production use.