docs: deployment overview + LXC server deploy + per-host agent install

2026-04-22 08:42:25 +02:00 · 2026-04-22 08:42:25 +02:00 · b06668fcbb
commit b06668fcbb
parent 585fbd0623
3 changed files with 280 additions and 0 deletions
--- a/agent/docs/install.md
+++ b/agent/docs/install.md
@ -0,0 +1,104 @@
+# Agent Install (per Proxmox host)
+
+## Prerequisites on the Proxmox host
+
+- Proxmox VE 8.3+ (OpenZFS 2.3+ for the `-j` flags on `zpool`/`zfs`)
+- Root SSH access
+- Outbound HTTPS to the monitor server
+
+No Erlang or Elixir needed — the Burrito binary ships its own runtime.
+
+## 1. Build the binary (operator workstation)
+
+```bash
+cd proxmox_monitor/agent
+./scripts/build-linux.sh            # requires Docker
+ls dist/
+# proxmox-monitor-agent_linux_amd64
+# proxmox-monitor-agent_linux_arm64
+```
+
+## 2. Register the host in the dashboard
+
+From the dashboard at `https://monitor.example.com/admin/hosts`:
+
+1. "Register a new host" → enter the short name (e.g. `pve-host-01`).
+2. Copy the one-time token shown.
+
+## 3. Copy files to the Proxmox host
+
+```bash
+HOST=pve-host-01
+scp dist/proxmox-monitor-agent_linux_amd64 \
+    root@$HOST:/usr/local/bin/proxmox-monitor-agent
+ssh root@$HOST 'chmod 0755 /usr/local/bin/proxmox-monitor-agent'
+
+# systemd unit (included in the repo)
+scp rel/proxmox-monitor-agent.service \
+    root@$HOST:/etc/systemd/system/
+```
+
+## 4. Write the config
+
+On the Proxmox host:
+
+```bash
+install -d -m 0700 /etc/proxmox-monitor
+cat > /etc/proxmox-monitor/agent.toml <<EOF
+server_url = "wss://monitor.example.com/socket/websocket"
+token = "<paste-token-from-dashboard>"
+host_id = "pve-host-01"
+
+[intervals]
+fast_seconds = 30
+medium_seconds = 300
+slow_seconds = 1800
+EOF
+chmod 0600 /etc/proxmox-monitor/agent.toml
+```
+
+## 5. Enable the service
+
+```bash
+install -d -m 0700 /var/cache/proxmox-monitor-agent
+systemctl daemon-reload
+systemctl enable --now proxmox-monitor-agent
+journalctl -u proxmox-monitor-agent -f
+```
+
+Expected within ~10s:
+```
+agent: starting with host_id=pve-host-01
+reporter: connected, joining host:pve-host-01
+reporter: joined host:pve-host-01
+```
+
+The host's card on the dashboard should flip to `online`.
+
+## 6. Token rotation
+
+If a token leaks: dashboard → Admin → "Rotate". Copy the new token, update
+`/etc/proxmox-monitor/agent.toml` on the affected host, `systemctl restart
+proxmox-monitor-agent`. Old token is invalidated immediately.
+
+## 7. Upgrade flow
+
+```bash
+# operator
+./scripts/build-linux.sh
+scp dist/proxmox-monitor-agent_linux_amd64 root@$HOST:/usr/local/bin/proxmox-monitor-agent.new
+
+# on the host
+mv /usr/local/bin/proxmox-monitor-agent{.new,}
+systemctl restart proxmox-monitor-agent
+```
+
+## Troubleshooting
+
+| Symptom                                 | Check                                                           |
+|------------------------------------------|-----------------------------------------------------------------|
+| `enoent` errors for `zpool`/`pvesh`      | You're not on a Proxmox host, or binaries aren't in `$PATH`.    |
+| `handshake_failed: :nxdomain`            | DNS for the monitor hostname fails from this host.              |
+| `unknown_host` rejection on join          | Host name in `agent.toml` doesn't match the dashboard entry.    |
+| `invalid_token` rejection                 | Token was rotated; paste the new one.                           |
+| Agent reconnects every 30s                | Server's WebSocket timeout hit — check Caddy `read_timeout 90s`.|