docs/beszel.md

@@ -0,0 +1,192 @@
+# 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.
+
+This document explains how to wire beszel-agent into any build in the flake.
+
+---
+
+## How it is split across modules
+
+There are two modules and they have separate jobs:
+
+| Module | What it does | Where it goes |
+|---|---|---|
+| `modules/beszel/enable-agent.nix` | Enables the systemd service, sets `HUB_URL`, fixes upstream StateDirectory bug | **Build type** (`modules/build-types/*.nix`) |
+| `modules/beszel/host-token.nix` | Declares the sops secret + env-file template that holds `TOKEN` | **Host file** (`hosts/<name>/host.nix`) |
+
+`KEY` (the hub's public key for this agent slot) is a plain string set
+directly on the host under `services.beszel.agent.environment.KEY` — it comes
+from the hub UI, not from sops, so it belongs in the host file rather than a
+secret.
+
+---
+
+## Adding beszel to a new build type
+
+Open `modules/build-types/<type>.nix` and add `../beszel/enable-agent.nix` to
+the `imports` list:
+
+```nix
+imports = [
+  ../beszel/enable-agent.nix
+  # ... other imports
+];
+```
+
+That is the only change needed at the build-type level. The module sets:
+- `services.beszel.agent.enable = true`
+- `HUB_URL` pointing at `docker.sweet.home:8090`
+- a persistent `StateDirectory` for the hub-pairing fingerprint
+
+---
+
+## Wiring the host file
+
+Every host whose build type includes `enable-agent.nix` needs two things in
+its `hosts/<name>/host.nix`:
+
+### 1 — Import `host-token.nix`
+
+```nix
+imports = [
+  (import ../../modules/beszel/host-token.nix {
+    name = "<hostname>";            # must match the sops secret file name below
+    sopsFile = ../../secrets/<hostname>.yaml;
+  })
+];
+```
+
+This creates a sops-managed env file at runtime containing `TOKEN=<value>` and
+passes it to the agent via `environmentFile`. The `name` argument also becomes
+the sops template name (`<name>-beszel.env`), so it must be unique per host.
+
+### 2 — Set `KEY` once the hub has paired the agent
+
+```nix
+services.beszel.agent.environment = {
+  KEY = "ssh-ed25519 AAAA...";
+};
+```
+
+`KEY` is the hub's SSH public key for this agent slot — copy it from the hub
+UI after the agent first connects (see "Pairing with the hub" below).
+
+Until the hub has been paired, leave `KEY` commented out or omit it. The agent
+will still start and appear in the hub as an unpaired entry; fill in the key
+after that first connection.
+
+---
+
+## Adding the sops secret
+
+The `beszel-token` value in `secrets/<hostname>.yaml` is the token the agent
+uses to authenticate to the hub. To add it for a new host:
+
+1. Decrypt and edit the host's secrets file:
+   ```sh
+   sops secrets/<hostname>.yaml
+   ```
+2. Add the token:
+   ```yaml
+   beszel-token: <token from the beszel hub UI>
+   ```
+3. Save and close — sops re-encrypts the file on exit.
+
+If the host does not yet have a `secrets/<hostname>.yaml`, create one using
+the same sops recipients as the other secrets files (check `.sops.yaml`), or
+run `scripts/secrets/sync-host-keys.sh <target>` first so the host's own
+SSH key is already a valid recipient.
+
+The token is found in the beszel hub under **Settings → Keys** or when you
+add a new system via the hub UI.
+
+---
+
+## Optional: monitoring extra filesystems
+
+To have the agent report disk usage for a mount point that is not the root
+filesystem, add `EXTRA_FILESYSTEMS` in the host file alongside `KEY`:
+
+```nix
+services.beszel.agent.environment = {
+  KEY = "ssh-ed25519 AAAA...";
+  EXTRA_FILESYSTEMS = "/mnt/data";   # colon-separated if more than one
+};
+```
+
+The `server` host uses this to expose the ZFS data pool:
+
+```nix
+EXTRA_FILESYSTEMS = "${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
+```
+
+---
+
+## Optional: monitoring Docker containers
+
+The `enable-agent.nix` module 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 in the hub. Hosts that do not run Docker should leave this commented out.
+
+---
+
+## Pairing with the hub
+
+1. Deploy the host with `host-token.nix` imported and `enable-agent.nix`
+   present in the build type. Leave `KEY` unset for now.
+2. Open the beszel hub (`http://docker.sweet.home:8090`).
+3. Go to **Systems → Add system**. The new host should appear as an
+   unpaired entry — copy the `KEY` value shown there.
+4. In `hosts/<name>/host.nix`, set:
+   ```nix
+   services.beszel.agent.environment.KEY = "<copied key>";
+   ```
+5. Rebuild and deploy the host. The agent will now pair permanently with the
+   hub.
+
+---
+
+## Example: complete host file
+
+For reference, `hosts/tor-relay/host.nix` is the minimal case — one
+filesystem, no Docker, LXC platform:
+
+```nix
+{ vars, ... }:
+{
+  imports = [
+    (import ../../modules/beszel/host-token.nix {
+      name = "tor-relay";
+      sopsFile = ../../secrets/tor-relay.yaml;
+    })
+  ];
+
+  networking = { ... };
+
+  services.beszel.agent.environment = {
+    KEY = "ssh-ed25519 AAAA...";
+  };
+
+  system.stateVersion = "26.05";
+}
+```
+
+`hosts/server/host.nix` is the fuller case — extra filesystem path, debug
+logging:
+
+```nix
+services.beszel.agent.environment = {
+  KEY = "ssh-ed25519 AAAA...";
+  EXTRA_FILESYSTEMS = "${vars.storageRoot}/${vars.nfsShares.dockerVolumes.subpath}";
+  LOG_LEVEL = "debug";
+};
+```