Swamp Worker

Site-specific: deploy a swamp worker to a set of fi.gy hosts over SSH — and completely remove it — driving the generic @svendowideit/swamp-worker model with @swamp/ssh. WHAT IT DOES

The concrete, private half of the worker setup: it supplies the fi.gy node set and runs the whole fan-out in one idempotent workflow. Run it once to enlist a set of hosts and again to upgrade them — it installs the swamp binary where absent, upgrades it where it differs, writes each node's systemd user unit and starts it, and fails unless the unit is active. Two matching workflows keep the fleet current: worker-rotate refreshes enrollment tokens without ever stranding a worker, and worker-teardown removes every worker and revokes its token so it can never re-enrol. Change the worker once on the orchestrator and re-run to reconcile every host. It is site-specific by design and useless without the fi.gy node set; the portable model is @svendowideit/swamp-worker and the SSH transport is @swamp/ssh.

INSTALL

swamp extension pull @figy/swamp-worker

DEPENDENCIES

@svendowideit/swamp-worker and @swamp/ssh (pulled separately), a reachable fi.gy swamp serve the workers dial, and OpenSSH key access to the nodes. The serve must speak the same worker protocol as the release installed on the nodes, so keep it current with swamp model method run swamp-serve updateBinary. A figy-trusted swamp repo (swamp extension trust add figy) so the pull resolves.

RUN

# Create the generic worker model once. `identity` namespaces the worker;
# `swampBinPath` MUST be the swamp binary on THIS orchestrator (it mints the
# tokens) and is the same path the provisioning script installs on each node;
# `otelSettingsModel=otel` wires each worker unit to export OTel logs,
# metrics and traces to the fi.gy gateway.
swamp model create @svendowideit/swamp-worker worker \
  --global-arg identity=figy \
  --global-arg swampBinPath=~/.local/bin/swamp \
  --global-arg otelSettingsModel=otel

# Install OR upgrade a set of nodes in one command; re-run it to reconcile.
swamp workflow run @figy/swamp-worker-upgrade \
  --input serveUrl=wss://swamp.x1yoga.fi.gy \
  --input 'hosts=[{"name":"host1","address":"host1.lan"}]'

# Rotate the enrollment tokens before they expire (never stranding a
# worker), bumping the generation each time — schedule this.
swamp workflow run @figy/swamp-worker-rotate \
  --input serveUrl=wss://swamp.x1yoga.fi.gy \
  --input 'hosts=[{"name":"host1","address":"host1.lan"}]' \
  --input generation=2

# Completely remove the deployed workers: the removal script runs on every
# node and each token is revoked on the orchestrator.
swamp workflow run @figy/swamp-worker-teardown \
  --input 'hosts=[{"name":"host1","address":"host1.lan"}]'

CONFIGURE

All three take hosts (the node set, each {name, address}), identity (worker identity, default figy, matching the generic model's global) and the SSH defaults sshUser, sshPort, sshKey and strictHostKeyChecking; upgrade also takes serveUrl (required), version (release to install, default latest) and duration (token lifetime, default 30d); rotate also takes generation (required) and previousSuffix. The generic model's globals (binary path, dirs, concurrency) are set on the worker model instance.

UPGRADE

Install and upgrade are the same workflow: re-run @figy/swamp-worker-upgrade to bring every node's worker up to version (default latest) and reconcile its unit. It is idempotent, reuses each node's staged token, and needs no new inputs.

WHAT IT INSTALLS

Nothing itself — it drives @svendowideit/swamp-worker on each node, which installs a systemd user unit swamp-worker-<identity>.service, the worker cache dir, and 0600 token/env files, and enables user lingering; and @swamp/ssh, the SSH transport. With otelSettingsModel=otel on the worker model, each worker unit also exports OTel logs, metrics and traces to the fi.gy gateway, attributed to the swamp-worker service with a per-node host=. Each node also needs a running systemd user manager (systemctl --user, i.e. a live logind and user@<uid>.service). No cron triggers or webhooks.