mrhid6
11b1936bb2
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.
2.6 KiB
id, title, sidebar_label
| id | title | sidebar_label |
|---|---|---|
| agent-updates | Agent updates | Agent updates |
Agents are versioned and released independently of the control plane, and update themselves on command.
Checking the current version
Each server's detail page shows the version it reported at its last sync.
GET /api/agent/latest-version reports the newest release available.
Updating from the UI
Servers → a server → Update agent pushes UpdateAgentCmd with a target
version. The agent then:
- Downloads the binary for its platform from the release.
- Verifies the SHA-256 against
checksums.txt. - Stops itself, replaces the binary in place, and starts again.
Restart=always on the systemd unit is what makes the last step work.
The server briefly goes offline and comes back within a poll interval or two.
Updating from the machine
There is a dynamic update script, the counterpart to the install one:
curl -fsSL https://vantage.example.com/update | bash
irm https://vantage.example.com/update.ps1 | iex
It does the same download, checksum and replace, then restarts the service. Use this when the control plane cannot push — for example, when the machine is reachable but its command stream is not.
Rolling out across a fleet
There is no built-in bulk update. Two reasonable approaches:
- Update from each server's page, a few at a time.
- Build a workflow whose step runs the update script, and target it at the machines you want. That gives you ordering, failure handling and a log.
:::tip Update a canary first
An agent that fails to start after replacing itself needs hands on that machine.
Do one, confirm it returns to active, then do the rest.
:::
Version compatibility
The gRPC API is versioned to tolerate an agent older than the control plane. The reverse — an agent newer than the control plane — is not a case anyone tests. Upgrade the control plane first.
Agents report their version on every SyncKeys, so a fleet running mixed
versions is visible in the server list rather than something you have to go
looking for.
If an update fails
| Symptom | Cause |
|---|---|
| "Checksum mismatch" | Interrupted download, or a proxy rewriting the body. Retry |
| Downloads nothing | The machine cannot reach gitea.hostxtra.co.uk |
| Service will not start afterwards | Wrong architecture binary, or the file was replaced while a different service manager held it. Reinstall with the install one-liner |
Reinstalling is always safe: the config file is left alone, so the agent comes back with the same identity and token.