Site-specific OpenTelemetry bootstrap for the fi.gy homelab — my domains, meshes, and tiers, wired into four workflows. WHAT IT DOES

The concrete, private half of an OpenTelemetry fleet setup. It supplies my observability contract — the dedicated otel.fi.gy sub-zone, the tailscale and wireguard gateway endpoints, home/sven attributes, and 14/90/7-day retention — to the generic @svendowideit models, and runs the whole publish path: render the contract, stage it versioned, serve it over HTTP(S) at settings.otel.fi.gy, proxy the OpenObserve UI at obs.otel.fi.gy, terminate TLS for the OTLP endpoint at otlp.fi.gy, reconcile the DNS records, and verify the live document. One @svendowideit/caddy model (otel-caddy) owns all otel Caddy config — records, wildcard TLS, and the settings, store-UI and OTLP routes. Prefer it over hand-editing settings on each host: change the contract once and every agent fetches it. This is site-specific by design — it encodes my domains, meshes, and gear, so it is useless without them; the portable model types live in @svendowideit.

INSTALL

swamp extension pull @figy/homelab-otel

DEPENDENCIES

@svendowideit/otel-settings, @svendowideit/otel-agent, @svendowideit/settings-server, @svendowideit/caddy, @svendowideit/otel-backend, @svendowideit/otel-gateway, @svendowideit/openobserve, and @svendowideit/fleet-inventory — pulled separately. A figy-trusted swamp repo (swamp extension trust add figy) so the pull resolves.

Docker, plus the store's admin login in a vault BEFORE running the backend bootstrap. The OpenObserve profile seeds its first admin user at first start, so both keys must exist or the container crash-loops:

swamp vault create @svendowideit/systemd-creds otel-openobserve-admin
swamp vault put otel-openobserve-admin ZO_ROOT_USER_EMAIL
swamp vault put otel-openobserve-admin ZO_ROOT_USER_PASSWORD

RUN

# Store the store's admin login first (the backend seeds it on first start).
swamp vault create @svendowideit/systemd-creds otel-openobserve-admin
swamp vault put otel-openobserve-admin ZO_ROOT_USER_EMAIL
swamp vault put otel-openobserve-admin ZO_ROOT_USER_PASSWORD

# Render, stage, serve, and verify the fi.gy observability contract.
swamp workflow run @figy/homelab-otel-bootstrap

Bring up the whole core node: store + gateway + DNS + TLS + named UI.

swamp workflow run @figy/bootstrap-otel-backend

Onboard a managed Debian/Ubuntu host onto the core node (Phase 2).

swamp workflow run @figy/host-onboard

Run this repo as an always-on swamp serve at swamp.x1yoga.fi.gy and

dashboard.x1yoga.fi.gy (dashboard + hot-reload + auto-resume on), with its

own telemetry pointed at the otel.fi.gy gateway.

swamp workflow run @figy/swamp-serve-bootstrap

Read the resolved contract for scripting.

swamp data get otel resolved --json

# Fetch the served machine contract.
curl https://settings.otel.fi.gy/otel.json

# Open the store UI (proxied by Caddy with the wildcard cert).
curl -I https://obs.otel.fi.gy/

# Confirm the public OTLP/HTTP endpoint terminates TLS (the gateway's own
# receiver is plaintext; Caddy terminates TLS on 443 for these agents).
curl -sI https://otlp.fi.gy/v1/logs

CONFIGURE

Each workflow takes optional --input overrides, so the same definitions run in each environment:

deploymentEnvironment   dev (this machine) | uat (T440s) | prod (Xeon)
settingsHostname        defaults to settings.otel.fi.gy
webroot                 directory Caddy serves the staged bundle from
bindAddress             address the store/gateway bind to (127.0.0.1 or a mesh address)
vaultName               vault holding the OpenObserve admin login
caddyModelName          Caddy model for the serve hostnames (default my-caddy)
otelSettingsModel       otel-settings model for the serve telemetry (default otel)

The site values themselves (domain, endpoints, meshes, retention) are fixed in the workflows' step globalArgs, because they are the point of this extension.

The @figy/homelab-otel model's only global arg is deploymentEnvironment (dev | uat | prod); homelab-otel describe emits the topology for it.

WHAT IT INSTALLS

It creates/updates swamp models and data; via @svendowideit/caddy it adds the settings route at settings.otel.fi.gy, and @figy/swamp-serve-bootstrap (via @svendowideit/swamp-serve and @svendowideit/systemd-service) installs a systemd user service running swamp serve, with Caddy routes and DNS for swamp.x1yoga.fi.gy and dashboard.x1yoga.fi.gy. No cron triggers or webhooks.