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/server/docs/deploy-lxc.md
+++ b/server/docs/deploy-lxc.md
@ -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
+```