docs: deployment overview + LXC server deploy + per-host agent install
This commit is contained in:
parent
585fbd0623
commit
b06668fcbb
3 changed files with 280 additions and 0 deletions
104
agent/docs/install.md
Normal file
104
agent/docs/install.md
Normal file
|
|
@ -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`.|
|
||||||
51
docs/deployment-overview.md
Normal file
51
docs/deployment-overview.md
Normal file
|
|
@ -0,0 +1,51 @@
|
||||||
|
# Deployment Overview
|
||||||
|
|
||||||
|
Two artifacts, built independently, deployed independently.
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────┐
|
||||||
|
│ Server (LXC in RZ) │
|
||||||
|
agents ──WSS─>│ - Phoenix release │
|
||||||
|
│ - SQLite │
|
||||||
|
│ - Caddy (TLS) │
|
||||||
|
└─────────────────────────┘
|
||||||
|
▲
|
||||||
|
│ ssh
|
||||||
|
│
|
||||||
|
┌─────────────────────────┐
|
||||||
|
│ Operator workstation │
|
||||||
|
│ - Builds server release│
|
||||||
|
│ - Builds agent binary │
|
||||||
|
└─────────────────────────┘
|
||||||
|
│ scp
|
||||||
|
▼
|
||||||
|
┌─────────────────────────┐
|
||||||
|
│ Proxmox host (any of N) │
|
||||||
|
│ - Burrito agent binary │
|
||||||
|
│ - systemd unit │
|
||||||
|
└─────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
## What runs where
|
||||||
|
|
||||||
|
| Component | Host | Port / Path |
|
||||||
|
|-----------|------|------------------------------------------|
|
||||||
|
| Caddy | Server LXC | 443 public, forwards → 127.0.0.1:4000 |
|
||||||
|
| Phoenix | Server LXC | 127.0.0.1:4000 (HTTP + WS) |
|
||||||
|
| SQLite | Server LXC | file at $DATABASE_PATH |
|
||||||
|
| Agent | Proxmox host | no listening ports |
|
||||||
|
|
||||||
|
## Secrets the operator must provide
|
||||||
|
|
||||||
|
| Variable | Where | How to generate |
|
||||||
|
|---------------------------|------------|-------------------------------------------------|
|
||||||
|
| `SECRET_KEY_BASE` | Server env | `mix phx.gen.secret` |
|
||||||
|
| `DASHBOARD_PASSWORD_HASH` | Server env | `mix run -e 'IO.puts(Argon2.hash_pwd_salt("..."))'` |
|
||||||
|
| Agent token | Server DB | Admin UI → "Add host" reveals it once |
|
||||||
|
|
||||||
|
## Build flow
|
||||||
|
|
||||||
|
1. `cd server && MIX_ENV=prod mix release` → produces `_build/prod/rel/server/`
|
||||||
|
2. `cd agent && ./scripts/build-linux.sh` → produces `dist/proxmox-monitor-agent_linux_amd64`
|
||||||
|
|
||||||
|
See `server/docs/deploy-lxc.md` and `agent/docs/install.md` for step-by-step.
|
||||||
125
server/docs/deploy-lxc.md
Normal file
125
server/docs/deploy-lxc.md
Normal file
|
|
@ -0,0 +1,125 @@
|
||||||
|
# Server Deployment (LXC + Caddy)
|
||||||
|
|
||||||
|
Target: a Proxmox LXC container running Debian 12 in the RZ, publicly reachable
|
||||||
|
on port 443 via Caddy. ~1 GB RAM, 2 cores, 10 GB disk covers >20 agents.
|
||||||
|
|
||||||
|
## 1. Create the LXC (on the hypervisor)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pct create 200 \
|
||||||
|
/var/lib/vz/template/cache/debian-12-standard_12.7-1_amd64.tar.zst \
|
||||||
|
--hostname proxmox-monitor \
|
||||||
|
--memory 1024 --cores 2 \
|
||||||
|
--rootfs local-zfs:10 \
|
||||||
|
--net0 name=eth0,bridge=vmbr0,ip=dhcp \
|
||||||
|
--unprivileged 1 --features nesting=0 --onboot 1
|
||||||
|
pct start 200
|
||||||
|
pct enter 200
|
||||||
|
```
|
||||||
|
|
||||||
|
## 2. Inside the LXC: base packages
|
||||||
|
|
||||||
|
```bash
|
||||||
|
apt-get update && apt-get install -y \
|
||||||
|
ca-certificates curl debian-keyring debian-archive-keyring apt-transport-https
|
||||||
|
# Caddy's apt repo
|
||||||
|
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | \
|
||||||
|
gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
|
||||||
|
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
|
||||||
|
> /etc/apt/sources.list.d/caddy-stable.list
|
||||||
|
apt-get update && apt-get install -y caddy sqlite3
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Upload the release
|
||||||
|
|
||||||
|
From the operator workstation:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd proxmox_monitor/server
|
||||||
|
MIX_ENV=prod mix release --overwrite
|
||||||
|
tar -czf server_release.tgz -C _build/prod/rel server
|
||||||
|
scp server_release.tgz root@<LXC-IP>:/tmp/
|
||||||
|
```
|
||||||
|
|
||||||
|
Back in the LXC:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p /opt/proxmox-monitor
|
||||||
|
tar -xzf /tmp/server_release.tgz -C /opt/proxmox-monitor
|
||||||
|
```
|
||||||
|
|
||||||
|
## 4. Directories & env file
|
||||||
|
|
||||||
|
```bash
|
||||||
|
install -d -m 0700 /var/lib/proxmox-monitor
|
||||||
|
cat > /etc/default/proxmox-monitor <<EOF
|
||||||
|
DATABASE_PATH=/var/lib/proxmox-monitor/monitor.db
|
||||||
|
SECRET_KEY_BASE=$(/opt/proxmox-monitor/server/bin/server eval 'IO.puts(64 |> :crypto.strong_rand_bytes() |> Base.encode64())' 2>/dev/null | tail -1)
|
||||||
|
DASHBOARD_PASSWORD_HASH='<paste from: mix run -e "IO.puts(Argon2.hash_pwd_salt(\"your-password\"))">'
|
||||||
|
PHX_SERVER=true
|
||||||
|
PHX_HOST=monitor.example.com
|
||||||
|
PORT=4000
|
||||||
|
EOF
|
||||||
|
chmod 0600 /etc/default/proxmox-monitor
|
||||||
|
```
|
||||||
|
|
||||||
|
## 5. systemd unit
|
||||||
|
|
||||||
|
```ini
|
||||||
|
# /etc/systemd/system/proxmox-monitor.service
|
||||||
|
[Unit]
|
||||||
|
Description=Proxmox Monitor Server
|
||||||
|
After=network-online.target
|
||||||
|
Wants=network-online.target
|
||||||
|
|
||||||
|
[Service]
|
||||||
|
Type=exec
|
||||||
|
EnvironmentFile=/etc/default/proxmox-monitor
|
||||||
|
ExecStartPre=/opt/proxmox-monitor/server/bin/server eval 'Server.Release.migrate()'
|
||||||
|
ExecStart=/opt/proxmox-monitor/server/bin/server start
|
||||||
|
ExecStop=/opt/proxmox-monitor/server/bin/server stop
|
||||||
|
Restart=always
|
||||||
|
RestartSec=5
|
||||||
|
User=root
|
||||||
|
|
||||||
|
[Install]
|
||||||
|
WantedBy=multi-user.target
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
systemctl daemon-reload
|
||||||
|
systemctl enable --now proxmox-monitor
|
||||||
|
journalctl -u proxmox-monitor -f # verify it listens on 4000
|
||||||
|
```
|
||||||
|
|
||||||
|
## 6. Caddy
|
||||||
|
|
||||||
|
```bash
|
||||||
|
install -m 0644 /opt/proxmox-monitor/server/lib/server-0.1.0/priv/docs/Caddyfile.example /etc/caddy/Caddyfile
|
||||||
|
# Edit monitor.example.com to match your real DNS.
|
||||||
|
nano /etc/caddy/Caddyfile
|
||||||
|
systemctl reload caddy
|
||||||
|
```
|
||||||
|
|
||||||
|
(If Caddy isn't the one in this LXC, copy the template to wherever Caddy lives.)
|
||||||
|
|
||||||
|
## 7. Create the first host
|
||||||
|
|
||||||
|
```bash
|
||||||
|
/opt/proxmox-monitor/server/bin/server rpc 'Server.Release.register_host("pve-host-01")'
|
||||||
|
```
|
||||||
|
|
||||||
|
Copy the printed TOKEN — you'll paste it into the agent config.
|
||||||
|
|
||||||
|
## 8. Upgrade flow
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# operator
|
||||||
|
cd server && MIX_ENV=prod mix release --overwrite
|
||||||
|
scp _build/prod/rel/server.tar.gz root@<LXC>:/tmp/server_release.tgz
|
||||||
|
|
||||||
|
# LXC
|
||||||
|
systemctl stop proxmox-monitor
|
||||||
|
tar -xzf /tmp/server_release.tgz -C /opt/proxmox-monitor --overwrite
|
||||||
|
systemctl start proxmox-monitor # ExecStartPre runs migrate automatically
|
||||||
|
```
|
||||||
Loading…
Add table
Add a link
Reference in a new issue