counterweight
fa9f7d10cd
First step of replacing Uptime Kuma and ntfy. Gatus runs on the new
observability VPS, fronted by Caddy at status.contrapeso.xyz.
Deployed as the upstream container image, not built from source. The role did
build from source first - their Dockerfile is a bare `CGO_ENABLED=0 go build`,
the Vue dashboard is compiled in via `//go:embed static` in web/static.go, and
CGO can stay off because the sqlite driver is pure-Go modernc.org/sqlite - but
that produces a binary upstream never ran, and it meant compiling the AWS SDK
and gRPC on the smallest box in the estate. That load was heavy enough that
unrelated Ansible tasks timed out while it ran. The cost of the container is a
daemon on the machine whose job is to notice when everything else breaks; that
trade is made deliberately and is written down in the role README.
Pinned by DIGEST, not tag. A tag is mutable - v5.36.0 can be repushed - so
pinning it alone is a weaker promise than it looks:
gatus_image: "ghcr.io/twin/gatus@sha256:c5f210d0..."
`docker compose pull` now either fetches exactly the reviewed image or fails.
gatus_version is kept beside it only so a human can read the release; the two
move together.
The image is FROM scratch, so it has no /etc/passwd and its default user is
root. The container runs as 10001:10001 with the host data dir owned to match,
plus read_only, cap_drop ALL, and no-new-privileges. NET_RAW is added back only
when gatus_allow_icmp, so the capability for icmp:// checks is a visible grant
rather than something inherited from running as root.
Config is a DIRECTORY, not a file. Gatus merges every *.yaml under
GATUS_CONFIG_PATH - maps deep-merge, lists append - so the role owns
00-base.yaml (web, storage, ui, alerting, security) and each service will drop
its own file into endpoints/, the same shape as caddy_site. A primitive defined
twice is ambiguous and upstream refuses it, so anything that is not a list lives
in the base file and nowhere else.
Two bugs the deploy caught:
* Gatus panics on a config with no endpoints ("configuration should contain at
least one endpoint or suite"), so "install now, add endpoints later" is not
a valid state. The role ships endpoints/00-self.yaml checking its own
/health. Less circular than it looks: it proves the directory merged, the
listener serves, and storage accepted a write.
* web.address was carried over from the systemd design as 127.0.0.1. Inside a
container that is the CONTAINER's loopback, which docker-proxy cannot reach
- gatus came up healthy, self-check passing, while every connection to the
published port was refused. It now always binds 0.0.0.0 inside the
container; the isolation comes from publishing to 127.0.0.1 on the host.
Auth is done at the edge, NOT with Gatus's own security.basic. Reading
api/api.go, that middleware protects exactly four routes - the statuses
endpoints. Everything else is registered on the unprotected router, including
/api/v1/config, every badge, and /api/v1/endpoints/:key/uptimes/:duration and
.../response-times/:duration/history, which return real data to anyone who can
guess a key ("<group>_<name>"). Verified against the live instance: all seven
routes returned 200 unauthenticated, and /uptimes/24h returned "1.000000".
So the vhost uses caddy_site_body with a path carve-out rather than
caddy_site_basic_auth, which has no way to exempt a path. The external-endpoint
push API must NOT sit behind basic auth: it authenticates with
`Authorization: Bearer <token>`, and basic auth wants the same header. It is not
unauthenticated - the handler 401s on a missing prefix, an empty token, or a
token that does not match that endpoint's own.
Verified end to end. All seven previously-open routes now 401. The push path
distinguishes cleanly: POST with no auth gets Gatus's own "invalid Authorization
header" with NO WWW-Authenticate; POST with a bogus Bearer gets 404 (key looked
up, no external endpoints yet); GET on the same path gets Caddy's 401 with
WWW-Authenticate: Basic, so the exemption is scoped to POST alone. The
self-check still passes because it polls localhost inside the container and
never traverses Caddy.
The host itself was rebuilt from scratch: 01 (ok=9 changed=8), 02 (ok=12
changed=6), 910_docker (--limit, since that playbook still wrongly claims all of
`managed` needs Docker), caddy (ok=13 changed=8), gatus (ok=18 changed=2).
Not done here: gatus_alerting is still {} - valid, and every condition is
evaluated and recorded, there is just nowhere to shout until a provider is
chosen to replace ntfy.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
4.5 KiB
gatus
Deploys Gatus — health checks, a status page,
and alerting — as the upstream container image, on the
observability group.
Why the container
Upstream publishes no binary release assets. The image is the only artefact
they ship and therefore the only one they test, so it is what docker run in
their README gets you, and it is what this role deploys.
Building from source is entirely possible — their Dockerfile is a bare
CGO_ENABLED=0 go build, the Vue dashboard is compiled in via //go:embed static in web/static.go, and the sqlite driver is pure-Go
modernc.org/sqlite so nothing needs linking. This role did that at first. The
reasons it doesn't now:
- It produces a binary upstream never ran.
- It means compiling the AWS SDK, gRPC and the Google API libraries on the smallest box in the estate. On this VPS that load was heavy enough that unrelated Ansible tasks timed out while it ran.
The cost of the container is a daemon on the machine whose job is to notice when everything else breaks. That is a real trade, made deliberately.
Pinned by digest, not by tag
gatus_image_digest: "sha256:c5f210d0…"
gatus_image: "ghcr.io/twin/gatus@{{ gatus_image_digest }}"
A tag is mutable — v5.36.0 can be repushed — so pinning the tag alone is a
weaker promise than it looks. The digest is a content address: if it resolves,
it is byte-for-byte the image reviewed here, and docker compose pull either
fetches exactly that or fails. gatus_version is kept alongside it purely so a
human can read which release it is; the two must be updated together.
What FROM scratch means for running it
The image has no /etc/passwd, so there is no user to drop to by name and the
default is root. The compose file runs it by numeric id (10001:10001) and the
data directory on the host is owned to match. Everything else is locked down to
approximate what the systemd unit used to do natively:
| systemd | compose |
|---|---|
ProtectSystem=strict |
read_only: true |
NoNewPrivileges=true |
security_opt: [no-new-privileges:true] |
CapabilityBoundingSet= |
cap_drop: [ALL] |
AmbientCapabilities=CAP_NET_RAW |
cap_add: [NET_RAW] (for icmp://) |
Configuration is a directory, not a file
GATUS_CONFIG_PATH points at /opt/gatus/config, and Gatus merges every *.yaml
underneath it — maps deep-merge, lists append. This role owns exactly one file:
/opt/gatus/config/00-base.yaml web, storage, ui, alerting, security (this role)
/opt/gatus/config/endpoints/*.yaml one file per service (gatus_endpoint)
A primitive defined in two files is ambiguous and upstream refuses it. So
anything that is not a list belongs in 00-base.yaml and nowhere else. Endpoints
are lists, so each service's file appends cleanly — the same shape as
caddy_site, where each service contributes its own vhost.
Pull and push
Gatus polls. For anything with a reachable HTTP or TCP surface that is the
better check, because it tests the path a user actually takes. The monitoring
host joins the headscale mesh via infra/920, so internal boxes are reachable
by MagicDNS name and can be polled directly rather than having to report in.
For state with no pollable surface — ZFS pool health, UPS mains status, disk usage, backup freshness — Gatus has external endpoints, a push API:
POST /api/v1/endpoints/{group}_{name}/external?success=true&error=&duration=
Authorization: Bearer <token>
with heartbeat.interval to alert when nothing reports in. That is the same
shape as the generic healthcheck_push_url already wired into every service
role, so those scripts need a URL, a POST, and an auth header — not a rewrite.
Variables
See defaults/main.yml. The ones that matter:
| Variable | Default | Note |
|---|---|---|
gatus_version / gatus_image_digest |
v5.36.0 / sha256:c5f210d0… |
must move together |
gatus_bind_address |
127.0.0.1 |
never bind publicly — the push API shares this listener |
gatus_storage_type |
sqlite |
memory loses all history on restart |
gatus_alerting |
{} |
pass-through; any provider Gatus supports |
gatus_allow_icmp |
true |
adds back NET_RAW for icmp:// checks |
gatus_alerting empty is valid and is the current state: every condition is
still evaluated and recorded, there is just nowhere to shout yet.
Verifying
docker ps --filter name=gatus
docker logs gatus --tail 50
curl -s localhost:8080/health
ls /opt/gatus/config/endpoints/