Docs/Install Lighthouse

Install Lighthouse

The dashboard prints exact, copy-paste install commands when you create a new Lighthouse — including the freshly-minted token. This page is the reference for what the install actually does and how to operate it after the first run.

Mint a Lighthouse first

In the dashboard, Lighthouses → New Lighthouse, name it, click Create. The dialog returns a token. It's shown once. Pick your install path; the dialog includes a tab per option with the token already substituted.

Shell (Linux / macOS)

curl -fsSL https://lighthouse.statusharbor.io/install.sh \
  | LIGHTHOUSE_TOKEN=<your-token> sh

The script downloads the static binary, drops it in /usr/local/bin/lighthouse, registers a systemd unit (or launchd plist on macOS) and starts the agent. Re-running it upgrades the binary in place; systemd / launchd picks up the new one automatically.

Working dir: /var/lib/lighthouse — the agent buffers events here when the network drops, replays on reconnect.

Docker

docker run -d --name lighthouse --restart=on-failure \
  -e LIGHTHOUSE_TOKEN=<your-token> \
  ghcr.io/statusharbor/lighthouse:latest

Pin the tag (e.g. :1.4.0) instead of :latest for deterministic deploys.

To upgrade: docker pull the new tag, docker rm -f lighthouse, docker run again with the same env. Or use the Upgrade modal in the dashboard for the exact one-liner.

Helm (Kubernetes)

helm install lighthouse oci://ghcr.io/statusharbor/charts/lighthouse \
  --namespace status-harbor --create-namespace \
  --set token=<your-token>

Useful chart values:

image.tag — pin to a specific agent version
discovery.enabled — set to true to enable Ingress / Service discovery (see Discovery)
discovery.namespaces — list of namespaces to watch (defaults to all)

To upgrade in place: helm upgrade lighthouse ... --version <new> --reuse-values. --reuse-values keeps your token and config.

Terraform

See the Terraform provider docs for the full example. The agent is deployed via the deployment modules — Helm, Docker, or cloud-init for VMs.

Environment variables

Variable	Default	Notes
`LIGHTHOUSE_TOKEN`	—	Required. The token shown when you minted the Lighthouse.
`LIGHTHOUSE_DATA_DIR`	`/var/lib/lighthouse`	Where to buffer events during outages.
`LIGHTHOUSE_LOG_LEVEL`	`info`	`info` or `debug`. Debug redacts check inputs / outputs.
`LIGHTHOUSE_DISCOVERY_ENABLED`	`false`	Turn on k8s discovery.
`LIGHTHOUSE_DISCOVERY_NAMESPACES`	`*`	Comma-separated namespace list.

Network requirements

Outbound HTTPS to lighthouse.statusharbor.io only. No inbound ports. The agent connects on start and polls on a heartbeat interval (default 60s, server-configurable).

If the agent is in Kubernetes and you've enabled discovery, give it the cluster RBAC to list/watch Ingresses and Services — the Helm chart does this for you.