Mitchell-JohnsonandClaude Fable 5.1
3c0c504e35
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
82 lines
4.7 KiB
Markdown
82 lines
4.7 KiB
Markdown
# Ham Lab
|
|
|
|
Web-based Linux management console for bare-metal Linux, in the style of the Proxmox
|
|
web UI. Named after Ham the cat (see also HamTV).
|
|
|
|
Status: **v0.1** — persistent web terminals and a live Dashboard tab. Scope and roadmap in
|
|
[`PLAN.md`](PLAN.md).
|
|
|
|
## Runs on any Linux box
|
|
|
|
One static Go binary with the UI embedded: no cgo, no libc, no Node at runtime, no agents.
|
|
The same file runs on Debian, Ubuntu, Fedora, RHEL/Rocky/Alma, openSUSE, Arch and Alpine
|
|
(musl), on bare metal, VMs and containers. Builds: `amd64`, `arm64`, `arm` (ARMv6
|
|
hard-float and up, so every Raspberry Pi), `386`, `riscv64`.
|
|
|
|
```sh
|
|
sudo ./hamlab-linux-amd64 install # that's the whole install
|
|
```
|
|
|
|
or, from wherever `make release` output is served:
|
|
|
|
```sh
|
|
curl -fsSL https://hamlab-demo.bigham.dev/install.sh | sh # asks: user, address, HTTPS, firewall, password
|
|
curl -fsSL https://hamlab-demo.bigham.dev/install.sh | sh -s -- --yes # asks nothing, all defaults
|
|
curl -fsSL https://hamlab-demo.bigham.dev/install.sh | sh -s -- --listen 0.0.0.0:8100 --tls auto # flags go to `hamlab install`
|
|
```
|
|
|
|
`install.sh` is a wizard when there is a terminal (it reads answers from `/dev/tty`, so it
|
|
works piped from curl) and silent otherwise. Either way it picks the build for `uname -m`,
|
|
checks it against `SHA256SUMS` and runs `hamlab install`; re-running it upgrades in place.
|
|
`make publish` puts a release where that URL serves it (`HAMLAB_URL` points it elsewhere); run it beside the `hamlab-linux-*` files and it installs offline.
|
|
`hamlab install`:
|
|
|
|
- copies the binary to `/usr/local/bin` (`--prefix`), atomically;
|
|
- gets root through `sudo` or `doas` if you aren't root already, and runs the console as
|
|
**you** (`--user`), so terminals are your login shell with your rights;
|
|
- writes the config to `~/.config/hamlab/` (`--data`; an existing `~/apps/hamlab/` is kept)
|
|
and asks for the login password, or generates one and prints it once
|
|
(`--password-stdin` for scripts);
|
|
- registers a boot-time service with **systemd** or **OpenRC**, naming only groups that
|
|
exist on the host, and waits for `/healthz`; with neither init it prints the one line
|
|
to put under your own supervisor;
|
|
- says so when firewalld or ufw will block the port (`--open-firewall` opens it).
|
|
|
|
Re-running it upgrades in place and keeps config, user and password. `hamlab uninstall
|
|
[--purge]` reverses it.
|
|
|
|
What adapts to the host, rather than assuming Debian:
|
|
|
|
| | |
|
|
|---|---|
|
|
| Root | already root, else passwordless `sudo`, else passwordless `doas`; without any, the console is read-only where root is needed and says so |
|
|
| Updates tab | apt, dnf, zypper, pacman, apk: list, refresh, upgrade, install (pacman: all or nothing) |
|
|
| Services / timers | systemd of any age (JSON output where it exists, the plain table before v246); a clear message on hosts without systemd |
|
|
| Disks | `lsblk`, or `/sys/block` when it's missing (busybox) or too old; SMART and ZFS only when their tools are there |
|
|
| Dashboard | `/proc` and `/sys` only: hwmon or thermal-zone temps, fans, NICs, disks, mounts; empty sections where the hardware has nothing to report. UPS from whichever of `pwrstat`, NUT (`upsc`) or `apcupsd` is installed |
|
|
| Listen address | bound with `IP_FREEBIND`, so a LAN address that isn't up yet at boot doesn't fail the start |
|
|
| Self-update | the new build must run and load this host's config before it replaces the old one; atomic rename; the daemon then re-execs itself, so it restarts the same way under systemd, OpenRC or nothing; `hamlab.prev` kept |
|
|
|
|
Building: `make build` (web + Go), `make release` (every architecture, `install.sh` and
|
|
`SHA256SUMS` in `dist/`), `make test`.
|
|
|
|
Terminals run as the user the service runs as, with that user's login shell.
|
|
|
|
## Managing several machines
|
|
|
|
Install Ham Lab on each host; on the ones the hub should reach:
|
|
`hamlab install --listen <lan-ip>:8100 --tls auto` (a self-signed certificate is generated
|
|
on first start). Then on the hub, open **Machines**, enter a name, the address
|
|
(`https://host:8100`) and that machine's Ham Lab password once. The hub pins the
|
|
certificate, keeps an access token, and every tab works against the chosen machine
|
|
through the switcher at the top of the rail.
|
|
|
|
Updating: `make deploy` on the hub installs the new build there and then pushes it to
|
|
every managed machine (`hamlab push-nodes`), which install it and restart. The Machines
|
|
page flags machines running an older version and offers the same push per machine.
|
|
Mixed architectures are fine: `make deploy` also cross-compiles every other architecture,
|
|
and the hub sends each machine the build for its own.
|
|
|
|
- On `core` it is public at `https://hamlab.bigham.dev` behind Nginx Proxy Manager.
|
|
- Installable as a PWA.
|