Server rack management
  • TypeScript 92.7%
  • JavaScript 4.7%
  • Shell 1.8%
  • CSS 0.5%
  • PowerShell 0.3%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-28 18:56:36 -04:00
kiosk Installers pull from Forgejo; consolidate to single root README 2026-10-15 20:13:49 -04:00
status Installers pull from Forgejo; consolidate to single root README 2026-10-15 20:13:49 -04:00
web Fix Timeout issues? 2026-10-28 18:56:36 -04:00
.gitattributes Initial commit 2026-10-07 03:23:36 -04:00
.gitignore Ignore local env and build artifacts 2026-10-12 18:37:20 -04:00
egg-saltbox-rack.json Installers pull from Forgejo; consolidate to single root README 2026-10-15 20:13:49 -04:00
README.md Installers pull from Forgejo; consolidate to single root README 2026-10-15 20:13:49 -04:00
TODO Update TODO 2026-10-16 14:22:48 -04:00

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.