Worker Onboarding

The install snippet

The Hosts page in the master UI generates this snippet for every new host. It is the only thing you ever paste on a worker — every field is auto-filled by the master at the moment you create the host record.

docker run -d \
  --name contextbay-worker \
  --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v contextbay-worker-data:/var/lib/contextbay \
  -e CONTEXTBAY_MASTER_URL=http://<MASTER_LAN_IP>:7480 \
  -e CONTEXTBAY_MASTER_ADDR=<MASTER_MESH_IP>:7481 \
  -e CONTEXTBAY_NODE_NAME=<worker-1> \
  -e CONTEXTBAY_ENROLL_TOKEN=<one-time-token-from-ui> \
  -e CONTEXTBAY_SHARED_SECRET=<shared-secret-from-ui> \
  ghcr.io/contextbay/contextbay-worker:latest

<MASTER_MESH_IP> is the master's address on the Headscale mesh, in the 100.64.0.0/10 CGNAT range — the master is always assigned 100.64.0.1, so the shape is the same on every install.

What every env var means

Every variable also accepts a sibling _FILE form (Docker secret idiom). For example, set CONTEXTBAY_SHARED_SECRET_FILE=/run/secrets/cb_shared_secret and CB will read the file contents instead of the inline value.

Why two master addresses?

A brand-new worker can't join the encrypted mesh until it has an authkey, and it can't get an authkey without calling the master's API. Catch-22 — solved by two distinct addresses with strictly different lifetimes:

• CONTEXTBAY_MASTER_URL (LAN HTTP) — used once for POST /api/enroll. After this call returns, this URL is never used again. It does not need to be reachable in steady state.
• CONTEXTBAY_MASTER_ADDR (mesh gRPC) — used for everything after enrollment. Heartbeats, metrics, events, command stream — all flow over WireGuard. This is the address you actually depend on long-term.

You can drop the LAN URL from your firewall rules entirely once all workers are enrolled — only the mesh-side gRPC port matters.

The bootstrap call

On startup the worker reads the env, decides whether enrollment is needed (token present + state dir empty), and runs the handshake:

Worker (cmd/worker)                                   Master (internal/api)
  |                                                       |
  | read CONTEXTBAY_* env                                 |
  | state dir empty + token present? → enroll             |
  |                                                       |
  | POST CONTEXTBAY_MASTER_URL/api/enroll  ────────────→  |
  |   { token, shared_secret }                            |
  |                                                       |
  |                          shared-secret check (CT cmp) |
  |                          GetEnrollmentByToken         |
  |                          mint Headscale pre-auth key  |
  |                          ConsumeEnrollment (atomic)   |
  |                          flip node → "monitoring"     |
  |                                                       |
  | ←──────────────────  200 OK { headscale_authkey,      |
  |                              control_url,            |
  |                              master_mesh_addr,       |
  |                              node_id }               |
  |                                                       |
  | tsnet.Up(authkey, control_url) → join mesh            |
  | persist state to /var/lib/contextbay/tsnet/           |
  |                                                       |
  | gRPC dial CONTEXTBAY_MASTER_ADDR  ─────────────────→  |
  |   stream Heartbeat / ReportMetrics / ReportEvents     |

From the moment the gRPC stream opens, the LAN URL is irrelevant. The Headscale control-plane URL returned by the master can be overridden with [mesh].headscale_public_url on the master — useful when CB sits behind a reverse proxy whose Host header doesn't match the worker-facing URL.

Enrollment rejection reasons

Every /api/enroll rejection is tagged with a reason code (also the reason label on the contextbay_enroll_rejections_total Prometheus counter). The host detail page shows the most recent attempts:

Fuse: from monitoring to fused

Enrollment alone gives you monitoring: heartbeats, metrics, Docker events, and a small command stream for log/exec proxying. To do container CRUD on the worker — start, stop, restart, redeploy stacks — you fuse the host.

Fuse is a deliberate second step because:

• It rolls out a Portainer Edge agent on the worker, which is a larger trust boundary than monitoring-only.
• It registers a new Portainer endpoint id with the master — CB then routes all container actions through Portainer for that endpoint.
• It must be admin-initiated (no auto-fuse) so you have a chance to inspect the host first.

Click Fuse on the host card or call POST /api/hosts/{id}/fuse. The fuse watchdog gives up after a deadline; failures are tagged with a source label on contextbay_fuse_failed_total (portainer_error or watchdog_timeout).

What you can do at each state

Persistence + container recreate

The worker container persists its mesh identity to /var/lib/contextbay (volume-mounted). If you recreate the container with the same volume:

• The worker does not re-enroll — the token has been consumed and would be rejected anyway.
• It detects that the tsnet state dir is non-empty and skips the bootstrap call entirely.
• tsnet brings up the existing identity, dials CONTEXTBAY_MASTER_ADDR, and resumes heartbeats.

If you delete the volume (or omit the volume mount on a new container) you must regenerate the token in the UI and run a fresh install snippet — the old token is gone.

Refreshing a worker

To deploy new worker code without re-enrolling, use make deploy-worker from the master's repo:

make deploy-worker WORKER=<worker-1> SSH_USER=ubuntu

# Optional override when both modes are present:
# MODE_OVERRIDE=systemd       # force systemd-managed binary
# MODE_OVERRIDE=docker-image  # force docker-image worker

The script:

• Builds the worker binary locally with the master's build flags (so versions stay aligned).
• scp's the binary to /opt/contextbay-worker/ on the remote host.
• Auto-detects whether the worker is managed by systemd or run as a docker-image, then restarts the appropriate unit/container. If both are present and you didn't pass MODE_OVERRIDE, the script refuses to act so you can't accidentally restart the wrong one.

Workers do not pull from a registry — the master scp's binaries directly. Keeps multi-arch builds explicit.