docs
cairnobs.org Demo Source
Esc

Install · 2 of 8

The server in a container

obs-beacond as one container with Docker or Podman, on SQLite in a volume: the simplest install after the packages, with a read-only root and no capabilities.

2 min read

The obs-beacond image holds the static binary, a CA bundle, the license and the third-party notices, and nothing else. It runs as user 1001 in group 0, needs no capabilities, and works with a read-only root. One container on SQLite is the setup here; for several copies with no gap during upgrades, run it on PostgreSQL (Scale and several copies).

Get the image

Each release's image is on GitHub's registry, for linux/amd64 and arm64:

docker pull ghcr.io/coffey-labs/cairnobs:0.1.0

:latest is the newest release. It's built from the same binaries as the release's packages, after their signature and checksums are checked.

To keep it in your own registry, OpenShift's internal one included:

skopeo copy --all docker://ghcr.io/coffey-labs/cairnobs:0.1.0 docker://registry.example.org/ops/obs-beacond:0.1.0

Or build it yourself from a release, with the script in the source (it needs docker buildx):

scripts/build-release.sh v0.1.0 dist      # or download the release's binaries into dist/
scripts/build-image.sh v0.1.0 dist         # writes dist/obs-beacond-image-v0.1.0.tar
scripts/build-image.sh v0.1.0 dist registry.example.org/ops/obs-beacond   # or pushes it

The archive is an OCI image index that docker load or podman load reads directly.

Set up

sudo mkdir -p /etc/obs-beacon
head -c 32 /dev/urandom | base64 | sudo tee /etc/obs-beacon/state.key >/dev/null   # keep a copy with your backups
sudo chmod 0640 /etc/obs-beacon/state.key && sudo chgrp 0 /etc/obs-beacon/state.key
sudo mkdir -p /var/lib/obs-beacon && sudo chown 1001:0 /var/lib/obs-beacon && sudo chmod 0770 /var/lib/obs-beacon

Rootless Podman maps user IDs: there, podman unshare chown 1001:0 /var/lib/obs-beacon, or mount it with :U.

/etc/obs-beacon/obs-beacond.yaml, at least:

listen: ":8150"
agent_listen: ":8461"
database: /var/lib/obs-beacon/beacon.db
state_key_file: /etc/obs-beacon/key/state.key
snapshot: /var/lib/obs-beacon/backup/beacon.db   # a consistent copy for your backups
alerts:
  public_url: https://obs.example.org
join:
  packages_url: https://git.coffeylabs.org/coffey-labs/cairnobs/releases/download/v0.1.0

The image doesn't carry the agent packages, so join.packages_url tells new hosts where to fetch them (Adding Linux hosts). Everything else in obs-beacond.yaml works here too.

Run

docker run -d --name obs-beacond --restart unless-stopped \
  -p 8150:8150 -p 8461:8461 \
  -v /var/lib/obs-beacon:/var/lib/obs-beacon \
  -v /etc/obs-beacon/obs-beacond.yaml:/etc/obs-beacon/obs-beacond.yaml:ro \
  -v /etc/obs-beacon/state.key:/etc/obs-beacon/key/state.key:ro \
  --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \
  ghcr.io/coffey-labs/cairnobs:0.1.0
docker logs obs-beacond 2>&1 | grep -A2 'first admin'

The log holds the one-time link for the first admin (Signing in).

  • Podman: the same line with podman. Rootless works, since nothing needs a port below 1024.
  • SELinux (RHEL family): add :Z to the data directory's mount (/var/lib/obs-beacon:/var/lib/obs-beacon:Z) and :z to the two files'.
  • HTTPS: put the web port behind your proxy, or publish 443 and 80 and let obs-beacond get its own certificate (HTTPS and addresses).
  • The agent port (8461) must reach the container untouched: agents use TLS with client certificates from Cairn OBS's own CA.

Upgrade

docker stop -t 30 obs-beacond && docker rm obs-beacond
docker run -d --name obs-beacond ...the same line, the new tag...

With one copy, the web interface is away for as long as the swap takes: 0.6 seconds in testing, from docker stop to the new version answering. Nothing is lost in that time:

  • Agents keep each report they can't send, on disk, and send the backlog once obs-beacond answers again. After an outage each waits a random few seconds first, so the fleet doesn't arrive at once.
  • Alerts held back before the stop are still held when it starts: incidents are in the database.
  • A host that went quiet only during the gap isn't called silent: for stale_after after a start, nothing is.

The database schema only ever grows, so the previous release runs on a database the new one has upgraded. Going back is the same steps with the old tag.

Back up

  • The file snapshot names: obs-beacond writes a consistent copy of the database there at start and every 6 hours (snapshot_every). Back that up, never the live file.
  • The state key, separately.

More in Its database and backups.