.github/workflows/release.yml runs on GitHub when a v* tag arrives through the mirror: it waits for Gitea's Release, checks SHA256SUMS's signature and every file against it, copies the Release to GitHub and builds the server image from those same binaries as ghcr.io/coffey-labs/cairnobs:<version> (and :latest for a final release). Gitea doesn't read .github/workflows, and every job waits on BUILD_ON=github like the other mirrored repos. The docs, the kustomize base and the join.image example now name that image; the image's labels point at the source and the docs. The "Private until launch" lines are gone.
4.2 KiB
The server in one container (Docker or Podman)
The obs-beacond image (kubernetes.md, The image) also runs on its
own, with Docker or Podman, on any Linux host. That's one copy on SQLite in
a volume: the simplest install after the packages. For several copies and
no gap during upgrades, run it on PostgreSQL instead (kubernetes.md, More
than one copy).
The image holds only the static binary, a CA bundle, the license and the third-party notices. It runs as user 1001 in group 0, needs no capabilities, and works with a read-only root.
Set up
mkdir -p /etc/obs-beacon
head -c 32 /dev/urandom | base64 > /etc/obs-beacon/state.key # keep a copy with your backups
chmod 0640 /etc/obs-beacon/state.key && chgrp 0 /etc/obs-beacon/state.key
mkdir -p /var/lib/obs-beacon && chown 1001:0 /var/lib/obs-beacon && 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 the backups
alerts:
public_url: https://obs.example.org # how people reach it; turns on passkeys over https
Everything else in formats.md 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'
With Podman, the same line with podman; rootless works, since nothing
needs a port below 1024. On RHEL-family hosts with SELinux, add :Z to
the data directory's mount (/var/lib/obs-beacon:/var/lib/obs-beacon:Z)
and :z to the two files'. For HTTPS, put the web port behind your proxy,
or publish 443 and 80 and let obs-beacond get its own certificate
(install.md). The agent port (8461) must reach the container untouched:
agents use TLS with client certificates from Cairn OBS's own CA.
Agents then join as on any install (install.md, Adding a host). The image
doesn't carry agent packages, so set join.packages_url.
Upgrade
docker pull ghcr.io/coffey-labs/cairnobs:0.2.0
docker stop -t 30 obs-beacond && docker rm obs-beacond
docker run -d --name obs-beacond ...the same line, the new tag...
Upgrading one copy has a gap: the web interface is away for as long as
the swap takes (0.6 s in testing, from docker stop to the new version answering). Nothing is lost:
- Agents keep each report they can't send, on disk, and send the backlog once obs-beacond answers again, marked as queued so it adds to the history without replacing the newest state. 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_afterafter 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
snapshot(above) writes a consistent copy of the database at start and everysnapshot_every(6 hours); back that file up, never the live one.- And, separately, the state key: without it the database's secrets can't be read, and obs-beacond won't start on it.
Tested
2026-11-13, Docker on Debian 13, with the options above (read-only root, no capabilities) and SQLite in a volume: 200 agents reporting every 15 s, through an upgrade from one build to the next under load.
- From
docker stopto the new version answering/readyz: 0.6 s. - 4 reports were refused in that time and sent again: of 2,000 reports made, 2,000 were taken, none lost.
- The new version started on the old one's database, snapshot and agent CA unchanged.