feat: documentation site

Docusaurus 3 docs-only site at docsite/, served statically by nginx under /docs on the marketing host. Covers getting started (self-hosted install through first server and first licence), the control plane, Vantage HQ, a reference section and operations. Wired into docker-compose.site.yml as docsite (3005:80) and into the image build workflow, rebuilding on its own directory only. Never added to the self-hosted compose file.
2026-07-28 15:46:33 +01:00
commit 11b1936bb2
44 changed files with 23669 additions and 0 deletions
@@ -0,0 +1,111 @@
+---
+id: agent-config
+title: Agent configuration
+sidebar_label: Agent config
+---
+
+The agent reads no environment variables. Everything is in one YAML file.
+
+## Location
+
+| Platform | Path |
+| --- | --- |
+| Linux | `/etc/vantage/config.yaml` |
+| Windows | `%ProgramData%\vantage\config.yaml` |
+
+Directory `0700`, file `0600`. The install script sets both.
+
+## Contents
+
+```yaml
+server_url: "vantage.yourdomain.com:9090"
+server_id: "<uuid>"
+pre_reg_token: "<token>" # removed after the first successful Register()
+agent_token: "" # written by the agent after Register()
+poll_interval: 30s
+tls: true
+```
+
+| Field | Meaning |
+| --- | --- |
+| `server_url` | `host:port` of the gRPC endpoint. Comes from the server's `GRPC_HOST` |
+| `server_id` | The identity issued when the enrolment was created |
+| `pre_reg_token` | Single-use, one hour. Cleared once registration succeeds |
+| `agent_token` | The permanent credential, written by the agent itself |
+| `poll_interval` | How often `SyncKeys` runs. Default `30s` |
+| `tls` | Whether to use TLS. Leave `true` |
+
+:::danger This file is the credential
+`agent_token` is plaintext here and nowhere else — the control plane holds only
+its SHA-256. Anyone who can read this file can act as this agent. That is why
+it is `0600` and the directory is `0700`.
+:::
+
+## Startup sequence
+
+```
+1. Load the config
+2. pre_reg_token present → Register() → save agent_token,
+   clear pre_reg_token, reconnect
+3. Start goroutines: command stream · hourly update check ·
+   inventory · monitors
+4. Enter the SyncKeys poll loop
+```
+
+## The poll loop
+
+```
+1. SyncKeys(server_id, agent_token, agent_version)
+2. Non-Linux hosts stop here — Windows agents register and heartbeat only
+3. Diff the desired keys against /root/.ssh/authorized_keys;
+   unchanged → write nothing
+4. Changed → write a temp file, os.Rename() over the real one, chmod 0600
+```
+
+## Service management
+
+### Linux
+
+Unit at `/etc/systemd/system/vantage-agent.service`, `Restart=always`, running
+as root.
+
+```bash
+systemctl status vantage-agent
+systemctl restart vantage-agent
+journalctl -u vantage-agent -f
+```
+
+### Windows
+
+A service registered through NSSM, or installed by the MSI that CI builds.
+
+```powershell
+Get-Service vantage-agent
+Restart-Service vantage-agent
+```
+
+## Command-line flags
+
+```
+vantage-agent -generate-key
+```
+
+Generates a keypair locally. Normal operation takes no flags.
+
+## Moving an agent to a new control plane
+
+Change `server_url`, clear `agent_token`, set a fresh `pre_reg_token` from a new
+enrolment, and restart. The old control plane still holds a server record that
+will go `offline`; delete it there.
+
+## Uninstalling
+
+```bash
+systemctl disable --now vantage-agent
+rm -f /usr/local/bin/vantage-agent /etc/systemd/system/vantage-agent.service
+rm -rf /etc/vantage
+systemctl daemon-reload
+```
+
+Keys already written to `authorized_keys` remain on disk — the agent is no
+longer running to remove them. Revoke first if that matters.