- TypeScript 92.7%
- JavaScript 4.7%
- Shell 1.8%
- CSS 0.5%
- PowerShell 0.3%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| kiosk | ||
| status | ||
| web | ||
| .gitattributes | ||
| .gitignore | ||
| egg-saltbox-rack.json | ||
| README.md | ||
| TODO | ||
SaltBox Rack status reporter
Primary: https://forgejo.hexium.cc/WilliamTheFatMan/SaltBoxRack (mirrored to GitHub as backup).
Status reporter (report.sh)
Install on the Linux host. Do not put sudo in front of this command.
curl -fsSL https://forgejo.hexium.cc/WilliamTheFatMan/SaltBoxRack/raw/branch/main/status/install-service.sh | bash
The installer prompts for the dashboard URL, status token, rack machine id, name, management IP, report interval, and whether to auto-add guests. It saves report.sh to ~/.local/share/saltbox-rack/report.sh and starts saltbox-rack-status.service as your user.
From a git checkout, the same installer copies the local report.sh instead of downloading it:
chmod +x status/install-service.sh status/report.sh
./status/install-service.sh
Follow the log:
sudo journalctl -u saltbox-rack-status.service -f
Each push prints the POST body, then the HTTP reply. The reply report object is the data that was sent: cpu, mem, uptime, status, mgmtIp, and vms (name, status, cpu, ram, ip). The vms counts above that (matched, updated, created, ignored) are how the rack applied guests, not the guest metrics.
After a change to report.sh:
sudo systemctl restart saltbox-rack-status.service
Status reporters are not Settings → Datasource connections (those are Proxmox / Pterodactyl / UniFi APIs). The agent POSTs to /api/status and updates an existing rack machine matched by id, name, or mgmt IP. Create that machine on the rack first. Unknown servers return 404 — reporters never create rack machines.
Guests: Proxmox VMs via qm list (if present), else libvirt domains via virsh, plus Docker or Podman containers with name, Running/Stopped, and container IP when available. Set auto-add to true so new guests appear under the machine in the rack UI.
Stats agent (node-exporter websocket)
Run on each server. Scrapes that host's node-exporter and serves a websocket for the stats page. Does not write the rack database.
curl -fsSL https://forgejo.hexium.cc/WilliamTheFatMan/SaltBoxRack/raw/branch/main/status/install-exporter.sh | bash
The installer asks for a listen port (3210) and the local exporter URL (http://127.0.0.1:9100). It installs Node.js 22 when the host has no Node 18 or newer, installs and starts node-exporter on port 9100 when that port is down, then installs saltbox-rack-exporter.service. Needs sudo and systemd. Logs: journalctl -u saltbox-rack-exporter.service -f.
Kiosk (Raspberry Pi display)
Runs a Pi with a screen as a dedicated display for the stats page in full-screen Firefox. Run as the desktop user, not with sudo:
curl -fsSL https://forgejo.hexium.cc/WilliamTheFatMan/SaltBoxRack/raw/branch/main/kiosk/install.sh | bash
Then sudo reboot. The display shows a pairing code; approve it under Settings → Kiosk (admin). Logs: journalctl -u saltbox-kiosk -f.
Self-update
Both the reporter and stats agent install a systemd timer that checks Forgejo every 5 minutes and refreshes the agent files when they change, restarting the service. No reinstall needed after pushing agent changes.
| Timer | Watches |
|---|---|
saltbox-rack-status-update.timer |
status/report.sh (+ the updater itself) |
saltbox-rack-exporter-update.timer |
status/exporter-ws/server.mjs, metrics.mjs, package.json (+ the updater itself) |
Config lives in ~/.config/saltbox-rack-status-update.env and ~/.config/saltbox-rack-exporter-update.env:
| Variable | Default | Meaning |
|---|---|---|
AUTO_UPDATE |
true |
Set false to stop checking (or sudo systemctl disable --now <timer>) |
UPDATE_HOST |
https://forgejo.hexium.cc |
Forgejo host to pull from |
UPDATE_REPO |
WilliamTheFatMan/SaltBoxRack |
Repo to pull from |
UPDATE_REF |
main |
Branch to track (set to a tag/sha to pin) |
FORGEJO_TOKEN |
empty | Only needed if the repo goes private |
Old installs pointing at WillFatty/SaltBoxRack are migrated to Forgejo automatically by the updater.