docs: Self review of doc pages
This commit is contained in:
@@ -4,64 +4,67 @@ title: Add your first server
|
||||
sidebar_label: Add your first server
|
||||
---
|
||||
|
||||
Enrolling a server means running one command on it. The control plane issues a
|
||||
short-lived token, the install script fetches the agent and writes a config, and
|
||||
the machine registers itself.
|
||||
Enrolling a server means running one command on it. Vantage issues a short-lived
|
||||
token, the install script fetches the agent and writes a config file, and the
|
||||
machine registers itself.
|
||||
|
||||
:::info You need a licence first
|
||||
An unlicensed install is read-only, so **Add server** will be refused until a
|
||||
licence is in place. If you have not done that yet, start with
|
||||
[Claim a Free licence](./claim-free-licence.md).
|
||||
:::
|
||||
|
||||
## 1. Create the enrolment
|
||||
|
||||
In the UI, go to **Servers → Add server** Then click the **Generate Install Command** button.
|
||||
This generates a server ID and a pre-registration token
|
||||
Go to **Servers → Add server**, then click **Generate install command**. Vantage
|
||||
creates a server record and an enrolment token for it.
|
||||
|
||||
:::warning The token is single-use and lives one hour
|
||||
It is the only credential in the flow, and it is spent the moment the agent registers.
|
||||
:::warning The token is single-use and lasts one hour
|
||||
It is the only credential in the flow, and it is spent the moment the agent
|
||||
registers. If it expires, generate a new command rather than reusing the old one.
|
||||
:::
|
||||
|
||||
## 2. Run the one-liner
|
||||
|
||||
### Linux
|
||||
|
||||
Run the generated install script as root.
|
||||
|
||||
Here is an example of the install script:
|
||||
Run the generated command as root. It looks like this:
|
||||
|
||||
```bash
|
||||
curl -fsSL "https://vantage.example.com/install?server_id=<id>&token=<token>" | bash
|
||||
```
|
||||
|
||||
What the script does:
|
||||
The script:
|
||||
|
||||
1. Detects architecture `x86_64` and `aarch64` only; anything else exits.
|
||||
2. Downloads the binary and `checksums.txt`, and **verifies the SHA-256**, aborting on a mismatch.
|
||||
3. Installs to `/usr/local/bin/vantage-agent`, mode `0755`.
|
||||
4. Writes the config file at `/etc/vantage/config.yaml`
|
||||
1. This contains the server ID, the pre-registration token and the gRPC host.
|
||||
5. Writes the systemd service file `/etc/systemd/system/vantage-agent.service` and starts the agent.
|
||||
1. Checks the architecture. Only `x86_64` and `aarch64` are supported.
|
||||
2. Downloads the agent and verifies its SHA-256 checksum, stopping on a mismatch.
|
||||
3. Installs the agent to `/usr/local/bin/vantage-agent`.
|
||||
4. Writes `/etc/vantage/config.yaml` with the server ID, the enrolment token and
|
||||
the address the agent connects to.
|
||||
5. Installs and starts the `vantage-agent` systemd service.
|
||||
|
||||
### Windows
|
||||
|
||||
Run this from an elevated PowerShell prompt:
|
||||
|
||||
```powershell
|
||||
irm "https://vantage.example.com/install.ps1?server_id=<id>&token=<token>" | iex
|
||||
```
|
||||
|
||||
Run from an elevated PowerShell.
|
||||
It writes the config to `%ProgramData%\vantage\config.yaml`, installs the agent
|
||||
as a Windows service and starts it.
|
||||
|
||||
What the script does:
|
||||
|
||||
1. Creates the config at `%ProgramData%\vantage\config.yaml`.
|
||||
1. This contains the server ID, the pre-registration token and the gRPC host.
|
||||
2. Downloads the agent MSI from Gitea.
|
||||
3. Installs the MSI and creates the Windows service.
|
||||
4. Starts the agent.
|
||||
|
||||
:::info Windows agents do **not** manage `authorized_keys` as this is a Linux-only function.
|
||||
:::info Windows servers do not get SSH key management
|
||||
Windows agents register, report inventory and run workflow steps. Managing
|
||||
`authorized_keys` is a Linux-only feature.
|
||||
:::
|
||||
|
||||
## 3. Watch it come up
|
||||
|
||||
The server appears immediately as `pending`. Within one poll interval, 30 seconds it becomes `active`.
|
||||
The server appears as `pending` straight away, and becomes `active` within about
|
||||
30 seconds.
|
||||
|
||||
Check the systemd logs using the following commands:
|
||||
On Linux you can watch the agent itself:
|
||||
|
||||
```bash
|
||||
systemctl status vantage-agent
|
||||
@@ -70,28 +73,30 @@ journalctl -u vantage-agent -f
|
||||
|
||||
## 4. Confirm it works
|
||||
|
||||
Open the server's detail page. Within a minute or two you should see:
|
||||
Open the server's page. Within a minute or two you should see:
|
||||
|
||||
- Status `active`, with a recent last-seen timestamp.
|
||||
- Inventory CPU, memory, swap, partitions, kernel. Metrics refresh every 30
|
||||
seconds; the full static snapshot every 15 minutes.
|
||||
- Pending OS updates, checked hourly.
|
||||
- Status `active`, with a recent last-seen time.
|
||||
- Inventory: CPU, memory, swap, partitions and kernel. Metrics refresh every 30
|
||||
seconds, and the fuller snapshot every 15 minutes.
|
||||
- Any pending OS updates, which the agent checks for hourly.
|
||||
|
||||
## If it does not appear
|
||||
|
||||
| Symptom | Cause |
|
||||
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Script exits at "Unsupported architecture" | Not amd64 or arm64 |
|
||||
| "Checksum mismatch!" | Interrupted download, or a proxy rewriting the body. Re-run |
|
||||
| "Could not determine latest agent version" | The host cannot reach `gitea.hostxtra.co.uk`, or no `agent/v*` release exists |
|
||||
| Service runs, server stays `pending` | The machine cannot reach `GRPC_HOST`. Test it from that machine |
|
||||
| Registers once then goes `offline` | Reachable for `Register` but not for the poll usually a firewall that permits the initial connection but drops the long-lived one |
|
||||
| Symptom | What to check |
|
||||
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
|
||||
| Script stops at "Unsupported architecture" | The machine is not 64-bit x86 or ARM |
|
||||
| "Checksum mismatch!" | An interrupted download, or a proxy rewriting the response. Run it again |
|
||||
| "Could not determine latest agent version" | The machine cannot reach the release host, or `GITEA_HOST` is not set on your control plane |
|
||||
| Service runs, server stays `pending` | The machine cannot reach the agent port. Test it from that machine, not from the control plane |
|
||||
| Registers, then goes `offline` | A firewall or proxy allows the first connection but drops the long-lived one |
|
||||
| "Server limit reached" | Your licence allowance is full. Raise it in Vantage HQ, or remove a server you no longer manage |
|
||||
|
||||
A server is marked `offline` when its last-seen time passes the threshold; that
|
||||
sweep runs every two minutes, so allow for it before concluding anything.
|
||||
A server is marked `offline` once it has not been seen for a while, and that
|
||||
check runs every couple of minutes, so give it a moment before concluding
|
||||
anything.
|
||||
|
||||
## Next Steps
|
||||
## Next steps
|
||||
|
||||
- [Assign an SSH key](../vantage/ssh-keys.md)
|
||||
- [Run a workflow](../vantage/workflows.md)
|
||||
- [Claim a Free licence](./claim-free-licence.md)
|
||||
- [Watch something with a monitor](../vantage/monitors.md)
|
||||
|
||||
Reference in New Issue
Block a user