Archived
beatzaplentyandClaude Sonnet 4.6
f22ff7db79
Check NixOS configurations / eval-hosts (pull_request) Successful in 10m59s
KEY (hub's SSH public key) is now stored in variables.nix as beszelHubKey and set by enable-agent.nix — no host file ever needs to touch it. TOKEN was already universal; this removes the last per-host beszel config. Importing enable-agent.nix in a build type is now the only step needed to add a new host to beszel monitoring. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
114 lines
3.1 KiB
Markdown
114 lines
3.1 KiB
Markdown
# Beszel agent
|
|
|
|
[Beszel](https://github.com/henrygd/beszel) is the monitoring dashboard used
|
|
in this LAN. The hub runs as a Docker container on `docker.sweet.home` (port
|
|
`vars.ports.beszelHub`, 8090). Each monitored NixOS host runs a
|
|
`beszel-agent` that connects back to the hub.
|
|
|
|
---
|
|
|
|
## How it works
|
|
|
|
Everything is handled by a single module:
|
|
|
|
**`modules/beszel/enable-agent.nix`** — imported by a build type. It:
|
|
- Enables `beszel-agent`
|
|
- Sets `HUB_URL` to `docker.sweet.home:8090`
|
|
- Sets `KEY` from `vars.beszelHubKey` (`variables.nix`) — the hub's SSH
|
|
public key, shared by every agent. Update `beszelHubKey` if the docker
|
|
host is ever rebuilt and the hub generates a new keypair.
|
|
- Reads the universal `beszel-token` from `secrets/common.yaml` via sops
|
|
and passes it to the agent as `TOKEN` in an env file
|
|
- Fixes an upstream bug where the agent couldn't persist its hub-pairing
|
|
fingerprint across restarts (adds a real `StateDirectory`)
|
|
|
|
A host file needs no beszel configuration at all — just import the module
|
|
in the build type and add the system in the hub UI.
|
|
|
|
---
|
|
|
|
## Adding beszel to a new build type
|
|
|
|
Add `../beszel/enable-agent.nix` to the `imports` list in
|
|
`modules/build-types/<type>.nix`:
|
|
|
|
```nix
|
|
imports = [
|
|
../beszel/enable-agent.nix
|
|
# ... other imports
|
|
];
|
|
```
|
|
|
|
That's the only change required. The host file needs nothing.
|
|
|
|
---
|
|
|
|
## Adding a new system to the hub
|
|
|
|
1. Rebuild and deploy the host with its build type importing `enable-agent.nix`.
|
|
2. Open the beszel hub (`http://docker.sweet.home:8090`).
|
|
3. Go to **Systems → Add system**, enter the host's IP and the default port
|
|
(45876). The agent will connect and the system will appear as active.
|
|
|
|
---
|
|
|
|
## One-time setup: add the token to `secrets/common.yaml`
|
|
|
|
The universal token is stored once in the common secrets file, shared by all
|
|
agents. Only needed once, not per-host:
|
|
|
|
```sh
|
|
sops secrets/common.yaml
|
|
```
|
|
|
|
Add:
|
|
```yaml
|
|
beszel-token: <token from the beszel hub Settings → Keys>
|
|
```
|
|
|
|
`secrets/common.yaml` is already a sops recipient for every host via their
|
|
SSH host keys, so no additional sops recipient setup is needed.
|
|
|
|
---
|
|
|
|
## Optional: monitoring extra filesystems
|
|
|
|
To report disk usage for a mount beyond the root filesystem, add
|
|
`EXTRA_FILESYSTEMS` in the host file:
|
|
|
|
```nix
|
|
services.beszel.agent.environment = {
|
|
EXTRA_FILESYSTEMS = "/mnt/data"; # colon-separated for multiple paths
|
|
};
|
|
```
|
|
|
|
The `server` host uses this to expose its ZFS data pool:
|
|
|
|
```nix
|
|
services.beszel.agent.environment = {
|
|
EXTRA_FILESYSTEMS = "${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
|
|
LOG_LEVEL = "debug";
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## Optional: monitoring Docker containers
|
|
|
|
`enable-agent.nix` has a commented-out line for Docker monitoring:
|
|
|
|
```nix
|
|
#DOCKER_HOST = "tcp://docker-socket-proxy:2375";
|
|
```
|
|
|
|
Uncomment it if the host runs docker-socket-proxy and you want per-container
|
|
stats. Hosts without Docker should leave it commented out.
|
|
|
|
---
|
|
|
|
## If the hub key changes
|
|
|
|
If the docker host is ever rebuilt and beszel generates a new SSH keypair,
|
|
update `beszelHubKey` in `variables.nix` and rebuild all beszel-enabled hosts.
|
|
The new key is visible in the beszel hub under **Settings → Keys**.
|