Workers and regions

Enrolling a worker

Two paths.

Dev / first worker. Set WORKER_ENROLLMENT_TOKEN in .env. The bundled worker in the Compose file uses it directly. This gets you a working stack out of the box.

Production / additional workers. Issue a one-shot enrollment token from the operator UI (Settings → Regions & workers → Issue token) or via the API:

curl -sS -X POST https://pulse.example.com/api/v1/workers/enroll-tokens \
    -H "Authorization: Bearer $PULSE_API_TOKEN" \
    -H 'Content-Type: application/json' \
    -d '{"region":"iad","ttl_seconds":900}'

Then on the remote box:

docker run -d --name pulse-worker --restart=always \
    -e API_URL=https://pulse.example.com \
    -e WORKER_REGION=iad \
    -e WORKER_ENROLLMENT_TOKEN=<token-from-above> \
    ghcr.io/your-org/pulse-worker:latest

The worker exchanges the enrollment token for a long-lived agent credential on first boot and persists it inside /var/lib/pulse.

Lifecycle controls

Per worker, from Settings → Regions & workers:

• Drain — stop accepting new jobs. The worker exits cleanly when its queue drains. Use before terminating a host.
• Restart — soft restart; worker re-enrolls with its persisted credentials.
• Remove — deletes the worker row. Any process still running becomes a zombie that can’t push heartbeats; clean it up on the host.

Regions

A region is a string label (iad, fra, sin, lhr, syd). Workers declare their region at enrollment; monitors choose which regions check them. Fresh installs seed a single region (iad) and run one bundled worker in it — no UI surfaces “regions” until you opt in.

Enabling multi-region monitoring

Multi-region is off by default. Turn it on when you have probes in more than one location:

1. Settings → Regions in the SPA. The page shows an empty-state CTA “Enable multi-region monitoring.” Click it.
2. The org flag multi_region_enabled flips to true, and the region UI reappears: the chip selector on monitor create/edit, per-region status pills on monitor detail, and the worker fleet view grouped by region.
3. Add a region row for each new location: pick a code (fra, lhr, etc.) and a friendly name. Lat/lon are optional and only used by the world-map visual.
4. Enroll a worker in that region: mint an enrollment token from Settings → Regions, run the worker binary on the remote VM with WORKER_REGION=<code> and WORKER_ENROLLMENT_TOKEN=<token> (see Workers above).
5. Monitors will now show a region chip selector. Only regions with at least one heartbeating worker are offered — you can’t accidentally target a region that has no probes.

You can also flip the flag off later. The schema rows and existing workers stay; the UI just collapses back to the single-region experience.

Network requirements for cross-region workers

A remote worker talks directly to Redis (for BRPOP on its region’s job queue) and to the API (for enrollment + heartbeat). Both must be reachable from the worker host. The pragmatic options:

• Managed Redis with TLS + ACL (rediss://user:pw@host:6380). Easiest.
• VPN / WireGuard between probe VMs and the primary.
• Cloudflare Tunnel / SSH tunnel in front of Redis.

Do not expose plain-text Redis on the public internet.

See Core concepts → Region rule for how multi-region results aggregate into a single monitor status.