From b9802e6b045a596a942ee1c915f1427de3dae11c Mon Sep 17 00:00:00 2001 From: mrhid6 Date: Tue, 4 Aug 2026 17:03:29 +0100 Subject: [PATCH] docs: Updated docs --- .../getting-started/claim-free-licence.md | 53 ++++++-------- docsite/docs/getting-started/first-login.md | 71 +++++++++---------- docsite/docs/getting-started/first-server.md | 68 +++++++----------- docsite/docs/hq/accounts-and-signup.md | 34 ++------- docsite/docs/hq/billing.md | 67 +++++------------ docsite/docs/hq/free-tier.md | 5 -- docsite/docs/hq/licensing-and-entitlements.md | 11 +-- docsite/docs/operations/agent-updates.md | 3 - docsite/docs/operations/backups.md | 9 +-- docsite/docs/reference/agent-config.md | 34 +-------- 10 files changed, 110 insertions(+), 245 deletions(-) diff --git a/docsite/docs/getting-started/claim-free-licence.md b/docsite/docs/getting-started/claim-free-licence.md index 58ac43c..f6ac6ab 100644 --- a/docsite/docs/getting-started/claim-free-licence.md +++ b/docsite/docs/getting-started/claim-free-licence.md @@ -10,67 +10,54 @@ HQ portal. ## What a licence is -A signed file. It carries the instance UUID it belongs to, the tier, the server +A signed file. It carries the instance ID it belongs to, the tier, the server allowance, feature toggles and an expiry. The control plane verifies the -signature locally checking a licence never contacts HQ, and a running instance -does not need HQ to be reachable. +signature locally. -Signing happens in exactly one place, in HQ. The control plane can only verify. +A running instance does not need HQ to be reachable. -## 1. Find your instance UUID +:::info One Free per account, per deployment. +The limit is enforced per account **and** deployment, so a Free cloud instance does not stop you claiming Free on a self-hosted install. +::: -In the control plane, go to **Settings → Licence**. The instance UUID is shown -there. It is the identity your licence binds to. +## 1. Find your instance ID -## 2. Link the install to your HQ account +In the control plane, go to **Settings → Licence**. The instance ID is shown there. + +## 2. Create a free license 1. Sign in at [Vantage HQ](https://vantage-hq.hostxtra.co.uk). If you have no account, see [Accounts and signup](../hq/accounts-and-signup.md). -2. Choose **Link an instance**. -3. Paste the instance UUID and give it a name you will recognise. +2. Click on the **Buy A Plan** button. +3. Click on **Self Hosted** then click on the **Free** plan, then finally Paste the instance ID and give it a name you will recognise. -Linking claims the UUID for your account. A UUID already linked elsewhere is -refused with a conflict rather than silently moved. +You will then see the new instance on the **Overview** page. -## 3. Claim Free +## 3. Downloading the free license -With the instance linked, choose **Claim Free** on it. HQ issues a Free licence -bound to that UUID and hands it back. +With the instance created go to the **Overview** page and expand the new instance. -:::info One Free per account, per deployment -The limit is enforced per account **and** deployment, so a Free cloud instance -does not stop you claiming Free on a self-hosted install. Both the friendly -pre-check and the issuer apply the same rule deliberately, because a -pre-check stricter than the issuer would refuse something that would actually -have worked. -::: +Click on the **View Instance Settings** button. You can then click on the **Download License** or the **Copy to clipboard** button. ## 4. Install the licence Download the licence from HQ and paste it in the control plane at **Settings → Licence**. -The instance validates the signature, checks the UUID matches its own, and +The instance validates the signature, checks the ID matches its own, and starts reporting the tier, allowance and expiry. -:::warning Cloud instances cannot paste a licence -On a cloud instance `POST /license` answers `409 cloud_managed`, and the UI -hides the form entirely. A cloud licence is written directly by HQ. This is not -a restriction the injection path has to work around it writes to the database, -not through the endpoint. +:::info Cloud instances do **not** require installing the license as this is done automatically. ::: ## Renewing Free licences are renewable from HQ within a renewal window near expiry; -outside that window the renew call refuses. See [Free tier](../hq/free-tier.md). - -Pasting a licence keeps working while the current one is expired that endpoint -is exempt from the licence check, because it is the way out of degraded mode. +outside that window you cannot renew early. See [Free tier](../hq/free-tier.md). ## Moving the install to new hardware -Rebuilding produces a new instance UUID, and a licence binds to a UUID. Use +Rebuilding produces a new instance ID, and a licence binds to a ID. Use **Relink** in HQ to move the licence across. The number of relinks per term is capped; the portal shows how many you have left. diff --git a/docsite/docs/getting-started/first-login.md b/docsite/docs/getting-started/first-login.md index 43d5b11..9580a31 100644 --- a/docsite/docs/getting-started/first-login.md +++ b/docsite/docs/getting-started/first-login.md @@ -4,7 +4,7 @@ title: First login sidebar_label: First login --- -A fresh install has no users and no organisation. The first visit creates both. +A fresh install has no users and no instance. The first visit creates both. ## 1. Bootstrap @@ -13,48 +13,49 @@ Open the control plane in a browser. Because no user exists, you land on Fill in: -| Field | Notes | -| ----------------- | ----------------------------------------------------------------- | -| Organisation name | Display name. Shown throughout the UI | -| Slug | Lowercase, used in the hostname on cloud. Some names are reserved | -| Your name | | -| Email | Becomes your sign-in identity | -| Password | Stored bcrypt-hashed | +| Field | Notes | +| ------------- | ------------------------------------- | +| Instance name | Display name. Shown throughout the UI | +| Email | Becomes your sign-in identity | +| Password | Stored bcrypt-hashed | -Submitting creates the organisation and its **owner** you. +Submitting creates the instance and its **owner** you. :::warning Bootstrap works exactly once The endpoint is open only while the database has no users. As soon as the first -one exists, `/setup` redirects to the login page and the bootstrap endpoint -refuses. There is no second chance to create the first owner, so record the -credentials before you close the tab. +one exists, There is no second chance to create the first owner, so record the +credentials before you continue. ::: -## 2. Sign in +## 2. Copy the Instance ID -You are taken to `/login`. Sign in with the email and password you just set. +Once you have finished setup you will see the successfully created page. -Sessions are an opaque 32-byte token in the `km_session` cookie, with the body -held in Redis for 24 hours. Restarting Redis signs everyone out and loses -nothing else. +This will show the Instance ID. You will need this ID when creating a license in the HQ. -## 3. Look around +## 3. Sign in -You land on the fleet dashboard, which is empty. The sidebar is the whole +Click the continue to sign in button on the successful setup page. + +You will be taken to `/login`. Sign in with the email and password you just set. + +## 4. Look around + +You land on the servers dashboard, which is empty. The sidebar is the whole product: -| Section | What it does | -| --------- | ----------------------------------------- | -| Servers | The fleet enrol, inspect, console, update | -| Keys | SSH public keys and their assignments | -| Workflows | Compose and run scripted work | -| Steps | The reusable step library | -| Monitors | HTTP, TCP, ICMP and TLS checks | -| Secrets | The encrypted vault | -| Audit | Every mutating action | -| Settings | Members, SSO, alerts, retention, licence | +| Section | What it does | +| --------- | ------------------------------------------ | +| Servers | The server enrol, inspect, console, update | +| Keys | SSH public keys and their assignments | +| Workflows | Compose and run scripted work | +| Steps | The reusable step library | +| Monitors | HTTP, TCP, ICMP and TLS checks | +| Secrets | The encrypted vault | +| Audit | Every mutating action | +| Settings | Members, SSO, alerts, retention, licence | -## 4. Add the rest of your team +## 5. Add the rest of your team Go to **Settings → Access**. Add members with a role: @@ -66,12 +67,6 @@ Go to **Settings → Access**. Add members with a role: Settings and organisation management require `owner` or `admin`. -If you would rather not manage passwords, configure single sign-on instead: -see [Settings](../vantage/settings.md#single-sign-on). You can add more than -one identity provider; each gets its own button on the login page, and no -buttons appear at all until at least one provider is configured. Client -secrets are stored encrypted. +If you would rather not manage passwords, configure single sign-on instead: see [Settings](../vantage/settings.md#single-sign-on). -## Next - -[Add your first server](./first-server.md). +You can add more than one identity provider; each gets its own button on the login page, and no buttons appear at all until at least one provider is configured. diff --git a/docsite/docs/getting-started/first-server.md b/docsite/docs/getting-started/first-server.md index 19c5a79..0e4ff81 100644 --- a/docsite/docs/getting-started/first-server.md +++ b/docsite/docs/getting-started/first-server.md @@ -4,41 +4,39 @@ title: Add your first server sidebar_label: Add your first server --- -Enrolling a machine means running one command on it. The control plane issues a +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. ## 1. Create the enrolment -In the UI, go to **Servers → Add server**. That calls `POST /api/servers/new`, -which generates a server ID and a pre-registration token and hands back a ready -one-liner. +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 :::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 -calls `Register`. If you paste it somewhere and come back tomorrow, create a new -enrolment instead nothing is lost by doing so. +It is the only credential in the flow, and it is spent the moment the agent registers. ::: ## 2. Run the one-liner ### Linux +Run the generated install script as root. + +Here is an example of the install script: + ```bash curl -fsSL "https://vantage.example.com/install?server_id=&token=" | bash ``` -Run it as root. The script: +What the script does: 1. Detects architecture `x86_64` and `aarch64` only; anything else exits. -2. Asks the Gitea API for the newest `agent/v*` release. -3. Downloads the binary and `checksums.txt`, and **verifies the SHA-256**, - aborting on a mismatch. -4. Installs to `/usr/local/bin/vantage-agent`, mode `0755`. -5. Writes `/etc/vantage/config.yaml` (directory `0700`, file `0600`) containing - the server ID, the pre-registration token and the gRPC host. -6. Writes `/etc/systemd/system/vantage-agent.service` with `Restart=always`, and - runs `systemctl enable --now vantage-agent`. +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. ### Windows @@ -46,42 +44,30 @@ Run it as root. The script: irm "https://vantage.example.com/install.ps1?server_id=&token=" | iex ``` -Run from an elevated PowerShell. The agent is registered as a service through -NSSM, with the config at `%ProgramData%\vantage\config.yaml`. There is also an -MSI built by CI if you would rather deploy that. +Run from an elevated PowerShell. -:::info Windows agents are second-class on purpose -They register, heartbeat, run workflow steps and report inventory. They do -**not** manage `authorized_keys` the key subsystem is Linux-only, and a -Windows agent stops after the heartbeat portion of the poll. +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. ::: ## 3. Watch it come up -The server appears immediately as `pending`. Within one poll interval 30 -seconds it flips to `active`. +The server appears immediately as `pending`. Within one poll interval, 30 seconds it becomes `active`. -On the machine: +Check the systemd logs using the following commands: ```bash systemctl status vantage-agent journalctl -u vantage-agent -f ``` -What happens on that first run: - -``` -1. Load /etc/vantage/config.yaml -2. pre_reg_token present → register → save agent_token, clear pre_reg_token -3. Reconnect with the permanent token -4. Start: command stream · hourly update check · inventory · monitors -5. Enter the key poll loop -``` - -After registration the config no longer contains the pre-registration token; it -contains a permanent agent token instead. The control plane stores only the -SHA-256 of that token, never the token itself. - ## 4. Confirm it works Open the server's detail page. Within a minute or two you should see: @@ -104,7 +90,7 @@ Open the server's detail page. Within a minute or two you should see: 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. -## Next +## Next Steps - [Assign an SSH key](../vantage/ssh-keys.md) - [Run a workflow](../vantage/workflows.md) diff --git a/docsite/docs/hq/accounts-and-signup.md b/docsite/docs/hq/accounts-and-signup.md index be2932b..e7e4be2 100644 --- a/docsite/docs/hq/accounts-and-signup.md +++ b/docsite/docs/hq/accounts-and-signup.md @@ -4,8 +4,7 @@ title: Accounts and signup sidebar_label: Accounts and signup --- -Vantage HQ, at `vantage-hq.hostxtra.co.uk`, is where you manage the **account** -behind your instances: your team, your instances, their licences and billing. +[Vantage HQ](https://vantage-hq.hostxtra.co.uk) is where you manage the **account**, your team, your instances, their licences and billing. ## An account is a team, not a person @@ -31,26 +30,15 @@ Signup is **account-first**. Creating an account creates the account and you; it does not create a Vantage instance. Nothing exists in any control plane until you later create or link one. -1. Go to the signup form. +1. Go to the [signup form](https://vantage.hostxtra.co.uk/start). 2. Enter your name, email and a password. 3. Check your email and click the verification link. -:::info Verify before you can sign in -An unverified account gets a distinct "check your email" message rather than a -generic authentication failure the address is already known to be yours, so -there is nothing to protect by being vague. -::: - -Verification links are valid for **24 hours**. The token is 32 random bytes and -only its SHA-256 hash is stored, so a leaked database yields no working links. - -If the verification email cannot be sent, the signup is rolled back rather than -left stranded retry rather than assuming a half-created account is in the way. +Verification links are valid for **24 hours**. ## Signing in -Email and password. The session is a cookie, separate from the control plane's: -signing in to HQ does not sign you in to an instance, and vice versa. +Use the Email and password used in the signup form to login to the HQ, signing in to HQ does not sign you in to an instance, and vice versa. ## What comes next @@ -65,14 +53,6 @@ signing in to HQ does not sign you in to an instance, and vice versa. Three destinations: **Overview**, **People**, **Billing**. -Settings lives in the account menu rather than the nav, because it is your -password rather than a place. The appearance toggle is there too. - -Overview lists your instances. Each is one record, closed to a row and open to -its licence contents, members and actions. It opens by default when it is your -only instance or when it needs attention, and your manual choice is remembered. - -There is deliberately no "your plan" card in the sidebar: tier, limits and -expiry belong to a **licence**, and a licence belongs to one instance. An -account with a Free cloud instance and a Professional self-hosted one has no -single plan to show. +- Overview lists your instances. +- People shows all the account members and their roles. +- Billing show the current subscriptions and subscription management. diff --git a/docsite/docs/hq/billing.md b/docsite/docs/hq/billing.md index f6d5e04..f720583 100644 --- a/docsite/docs/hq/billing.md +++ b/docsite/docs/hq/billing.md @@ -8,56 +8,29 @@ Paid plans are billed through **Paddle**, which is the merchant of record. Your invoice, your card details and your tax handling are all Paddle's; HQ holds a customer reference and nothing sensitive. -Billing is **owner-only**. +:::warning +The Billing page requires the **owner-only** account role. +::: -## Buying +## Buying A Plan + +Buying a plan license can be found in Vantage HQ by clicking on the **Buy a Plan** button on the **Overview** page. ### Cloud -Open the instance, change its configuration to what you want, and check out. -Checkout runs in the browser. +On the **Buy A Plan** page you will need to select the **Deployment** to **Cloud** then chose your **Billing** cycle (Monthly or Annually). + +Then select your desired **Plan** and configure the features. + +Finally specify the **Instance Name** and click the **Continue to payment** button. ### Self-hosted -**Buy self-hosted**, then bind the purchase to your install's UUID. See -[Self-hosted instances](./self-hosted-instances.md). +On the **Buy A Plan** page you will need to select the **Deployment** to **Self-Hosted** then chose your **Billing** cycle (Monthly or Annually). -## What you are buying +Then select your desired **Plan** and configure the features. -A subscription's line items are the configuration: the plan base, the metered -server count above the base, and any per-instance features. Changing the -configuration changes the line items. - -## Changing configuration - -**Instance → Configuration**, adjust servers or features, and save. - -- **Increases** take effect when the payment confirms. -- **Reductions** are scheduled for the end of the term. The portal shows the - date and the new value. - -## The customer portal - -**Billing → Manage** mints a Paddle customer-portal session where you can -update your payment method, see invoices and cancel. - -## How a licence follows a payment - -```mermaid -flowchart LR - C["Checkout / change"] --> P["Paddle"] - P -->|signed webhook| H["HQ"] - H --> G["Entitlement: desired → granted"] - G --> L["Licence signed from granted"] -``` - -The webhook is the **only** issuing path for paid plans. It is signature -verified, processed exactly once, and resolved from the subscription's _current_ -line items so a webhook that arrives out of order still produces the right -answer rather than replaying a stale state. - -A licence is signed from **granted** only. A checkout you abandon changes -nothing. +Finally specify the **Instance Name** and click the **Continue to payment** button. ## Cancelling and failed payments @@ -66,18 +39,12 @@ Your licence runs to its grace-padded expiry and then lapses normally. There is no mid-term cut-off. For a cloud Free instance, lapsing eventually leads to deletion see -[Free tier](./free-tier.md). Paid instances are not reaped. +[Free tier](./free-tier.md). Paid instances are not deleted. ## Renewals At renewal the subscription bills again and the licence is reissued for the new term. It is also the only moment a scheduled **reduction** takes effect. -Self-hosted customers: download and paste the reissued licence. Cloud customers: -nothing to do. - -## Free is not in Paddle at all - -Free has no subscription, no £0 line item and no Paddle record. It has its own -renewal, in the portal. An account only acquires a Paddle customer reference -with its first paid purchase. +- Self-hosted customers: download and paste the reissued licence. +- Cloud customers: the license is automatically linked to the instance. diff --git a/docsite/docs/hq/free-tier.md b/docsite/docs/hq/free-tier.md index d88ec02..8d50bae 100644 --- a/docsite/docs/hq/free-tier.md +++ b/docsite/docs/hq/free-tier.md @@ -25,11 +25,6 @@ features on a paid plan. The limit is enforced per account **and** deployment. A Free cloud instance does not prevent a Free self-hosted one they are separate slots. -## Free is outside Paddle - -There is no subscription, no £0 line item and no invoice. Your account acquires -a Paddle customer reference only with its first paid purchase. - ## Renewing Free licences have a term and must be renewed from the portal. diff --git a/docsite/docs/hq/licensing-and-entitlements.md b/docsite/docs/hq/licensing-and-entitlements.md index 3a9bfbc..05dbc0a 100644 --- a/docsite/docs/hq/licensing-and-entitlements.md +++ b/docsite/docs/hq/licensing-and-entitlements.md @@ -30,9 +30,9 @@ entitlement. Two are per-instance toggles rather than tier bundles: -| Feature | What it enables | -| --------- | ------------------------------------------------------------------------- | -| `console` | The [browser console](../vantage/browser-console.md) | +| Feature | What it enables | +| --------- | -------------------------------------------------------------------- | +| `console` | The [browser console](../vantage/browser-console.md) | | `oidc` | Per-instance [single sign-on](../vantage/settings.md#single-sign-on) | No tier includes them by default; you enable them on the instances that need @@ -88,8 +88,3 @@ or let it be written for you (cloud). When you exceed your server allowance, enrolling another one is refused. The existing fleet is unaffected. Raise the allowance in the portal, or remove a server you are not using. - -## Legacy tiers - -An older `self_hosted` tier is mapped forward to self-hosted Professional -wherever it appears. Nothing needs doing about it. diff --git a/docsite/docs/operations/agent-updates.md b/docsite/docs/operations/agent-updates.md index a3b92eb..6a974c6 100644 --- a/docsite/docs/operations/agent-updates.md +++ b/docsite/docs/operations/agent-updates.md @@ -10,7 +10,6 @@ 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 @@ -21,8 +20,6 @@ version. The agent then: 2. Verifies the SHA-256 against `checksums.txt`. 3. 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 diff --git a/docsite/docs/operations/backups.md b/docsite/docs/operations/backups.md index 8eff3e5..f49fee0 100644 --- a/docsite/docs/operations/backups.md +++ b/docsite/docs/operations/backups.md @@ -52,16 +52,9 @@ cp /opt/vantage/.env /secure-location/vantage.env Treat it as a credential in its own right it holds the encryption key. -## Run logs - -Workflow run logs live in the `./data` bind mount, not in the database. They are -swept on the retention schedule anyway, so most people do not back them up. If -you keep them for compliance, set retention to `0` (forever) and include the -directory. - ## What a restore gives you -Everything: fleet, keys, assignments, workflows and their history, monitors and +Everything: server, keys, assignments, workflows and their history, monitors and incidents, secrets, settings and the audit log. What it does **not** do is reconcile the world. After a restore: diff --git a/docsite/docs/reference/agent-config.md b/docsite/docs/reference/agent-config.md index 3e26bba..26041e8 100644 --- a/docsite/docs/reference/agent-config.md +++ b/docsite/docs/reference/agent-config.md @@ -37,31 +37,9 @@ tls: 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`. +its SHA-256. Anyone who can read this file can act as this agent. ::: -## Startup sequence - -``` -1. Load the config -2. pre_reg_token present → register → save agent_token, - clear pre_reg_token, reconnect -3. Start: command stream · hourly update check · inventory · monitors -4. Enter the key poll loop -``` - -## The poll loop - -``` -1. Ask the control plane for the desired key state, reporting the - 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, rename it over the real one, chmod 0600 -``` - ## Service management ### Linux @@ -77,21 +55,13 @@ journalctl -u vantage-agent -f ### Windows -A service registered through NSSM, or installed by the MSI that CI builds. +A service registered through NSSM, or installed by the MSI. ```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