keryx-status (notify.wantok.cz)

Queryable current-condition snapshots for Keryx. SafeCall installations PUT a replace-in-place document; phones GET it with the QR token. The service runs beside ntfy on the notify host (hetest2 / SSH alias mnew.ssh today), not on the binary update host.

Operator log: OA-keryx-status-sidecar. How-to for nginx on a client notify host: ntfy-deployer.

Do not put KERYX_STATUS_READ_SECRET, ntfy tokens, or .env files in git.

Automatic deploy

On each release commit (bun commit → server build via scripts/build/server.sh):

1. SafeCall binaries upload to /home/thomas/updates/ on mnew.ssh
2. Bug collector deploys to the update host
3. scripts/build/keryx-status.sh runs tests, compiles releases/keryx-status-x64, SCPs it to mnew.ssh:/home/thomas/keryx-status/keryx-status.new, atomically renames it, and restarts the service:

sudo /bin/systemctl restart keryx-status.service

--server-only / --skip-upload on server.sh skips SafeCall artifact upload, bug-collector deploy, and keryx-status deploy.

Manual build (no upload):

./scripts/build/keryx-status.sh --skip-upload
# or from package:
cd keryx-status && bun test && bun run build

One-time server setup

Run on hetest2 (SSH mnew.ssh; machine hostname ihetest2) as a user with sudo. ntfy stays on /.

1. Directory

mkdir -p /home/thomas/keryx-status
chown thomas:thomas /home/thomas/keryx-status

2. Environment file

Create /home/thomas/keryx-status/keryx-status.env (never deployed from git):

KERYX_STATUS_PORT=8792
KERYX_STATUS_NTFY_URL=http://127.0.0.1:2586
KERYX_STATUS_DB_PATH=/home/thomas/keryx-status/keryx-status.db
KERYX_STATUS_MAX_BODY_BYTES=2000000
# Optional HMAC for phone GET on a shared notify host. Empty = ntfy subscribe token.
# KERYX_STATUS_READ_SECRET=replace-me

Store KERYX_STATUS_READ_SECRET in the approved secret store if used. When it is set, SafeCall server_keryx_status_read_secret on each install must match so minted QRs include status_token.

3. systemd

Create /etc/systemd/system/keryx-status.service:

[Unit]
Description=keryx-status
After=network.target

[Service]
Type=simple
User=thomas
WorkingDirectory=/home/thomas/keryx-status
ExecStart=/home/thomas/keryx-status/keryx-status
Restart=on-failure
EnvironmentFile=/home/thomas/keryx-status/keryx-status.env

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable keryx-status.service
sudo systemctl start keryx-status.service
sudo systemctl status keryx-status.service

4. sudoers

thomas ALL=(root) NOPASSWD: /bin/systemctl restart keryx-status.service

5. nginx

Keep ntfy on /. Proxy the sidecar under /keryx-status/ as in templates/nginx-ntfy.conf. Reload nginx after editing. Existing Keryx phones need a new QR after this is live so they subscribe to {server_id}-status and GET the snapshot.

Endpoints

Method	Path	Auth
PUT	/v1/sites/{server_id}/status	Bearer = SafeCall server_ntfy_publish_token (ntfy /v1/account)
GET	/v1/sites/{server_id}/status	HMAC status_token from the QR when KERYX_STATUS_READ_SECRET is set; otherwise ntfy subscribe token
GET	/v1/sites/{server_id}/status/{category}	Same as GET
GET	/health	none

Public URLs are /keryx-status/ + those paths.

Troubleshooting

Symptom	Check
Service fails after restart	journalctl -u keryx-status.service -n 50; env file; binary chmod +x
PUT 401	Publish token ACL includes {server_id}-status (or *); ntfy reachable at KERYX_STATUS_NTFY_URL
GET 401 on phones	New QR; HMAC secret mismatch; or subscribe token cannot read {server_id}-status
Overview waiting	Install can PUT (ntfy enabled); phone scanned a v2 QR with status_url