Vantage/vantage-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Self review of doc pages

Browse Source
This commit is contained in:
mrhid6
2026-08-10 16:32:23 +01:00
parent bd7b3256fc
commit 83c38db92e
34 changed files with 860 additions and 991 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/getting-started/claim-free-licence.md
+40 -31
View File
@@ -4,64 +4,73 @@ title: Claim a Free licence
sidebar_label: Claim a Free licence
---
A self-hosted install runs unlicensed until you give it a licence. Free is a
real tier in both deployments, and you can claim one for your install from the
HQ portal.
A self-hosted install stays read-only until you give it a licence. You claim a
Free one from Vantage HQ, and it takes a couple of minutes.
:::warning An unlicensed install is read-only
You can sign in and look around, but adding servers, keys, workflows and
everything else is refused until a licence is installed. Do this before
[adding your first server](./first-server.md).
:::
## What a licence is
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.
A signed file that names your instance, its tier, how many servers you may
manage, which features are enabled and when it expires. Your install checks the
signature itself, so it never has to reach Vantage HQ to work.
A running instance does not need HQ to be reachable.
:::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.
:::info One Free licence per account, per deployment
A Free cloud instance does not use up your Free self-hosted one. They are
separate.
:::
## 1. Find your instance ID
In the control plane, go to **Settings → Licence**. The instance ID is shown there.
Open the **Licence** page from the sidebar of your install. The instance ID is
shown at the top, and it is the value Vantage HQ asks for.
## 2. Create a free license
## 2. Create the instance in Vantage HQ
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. 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.
account yet, see [Accounts and signup](../hq/accounts-and-signup.md).
2. On **Overview**, choose **License my own install**. Once you already have an
instance, the same page offers **Buy a plan** instead.
3. Choose **Self-hosted**, then the **Free** plan.
4. Paste your instance ID, give the instance a name you will recognise, and
click **Create licence**.
You will then see the new instance on the **Overview** page.
The new instance now appears on the **Overview** page.
## 3. Downloading the free license
## 3. Download the licence
With the instance created go to the **Overview** page and expand the new instance.
Click on the **View Instance Settings** button. You can then click on the **Download License** or the **Copy to clipboard** button.
Expand the new instance on **Overview** and click **View Instance Settings**.
From there, use **Download licence** or **Copy to clipboard**.
## 4. Install the licence
Download the licence from HQ and paste it in the control plane at
**Settings → Licence**.
Back in your install, open the **Licence** page, paste the licence and save.
Your instance confirms the licence was issued to it, then shows your tier,
server allowance and expiry date.
The instance validates the signature, checks the ID matches its own, and
starts reporting the tier, allowance and expiry.
:::info Cloud instances do **not** require installing the license as this is done automatically.
:::info Cloud instances need none of this
A cloud instance is licensed automatically when it is created. These steps are
for self-hosted installs only.
:::
## Renewing
Free licences are renewable from HQ within a renewal window near expiry;
outside that window you cannot renew early. See [Free tier](../hq/free-tier.md).
Free licences run for a year. The renew button appears in Vantage HQ seven days
before expiry and stays available after it, so a lapsed instance can still be
rescued. See [Free tier](../hq/free-tier.md).
## Moving the install to new hardware
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.
A rebuilt install gets a new instance ID, and a licence only works for the ID it
was issued to. Use **Relink** in Vantage HQ to move the licence across. You get
three relinks per term, and the portal shows how many are left.
## Next
- [Add your first server](./first-server.md)
- [Licensing and entitlements](../hq/licensing-and-entitlements.md)
- [Buying a paid self-hosted licence](../hq/self-hosted-instances.md)
docs/getting-started/cloud-vs-self-hosted.md
+35 -37
View File
@@ -4,64 +4,62 @@ title: Cloud or self-hosted
sidebar_label: Cloud or self-hosted
---
Vantage runs in two deployments. They are the same software; what differs is
who operates it and how licensing, users and data lifecycle work.
Vantage runs in two ways. It is the same software; what differs is who runs it,
and how licensing and user accounts work.
## At a glance
| | Cloud | Self-hosted |
| --------------------- | --------------------------------------------------- | ------------------------------ |
| Who runs it | We do | You do |
| Where you sign in | `<your-slug>.vantage.hostxtra.co.uk` | Your own hostname |
| Database and backups | Ours | Yours |
| Licence | Written for you when you buy or create the instance | Pasted in, or claimed from HQ |
| Team members | Granted from HQ; the instance holds a projection | Created in the instance itself |
| Free tier | Yes, one per account | Yes, one per account |
| Expired Free instance | Eventually deleted, after warning | Never deleted |
| | Cloud | Self-hosted |
| --------------------- | ------------------------------------------- | ------------------------------ |
| Who runs it | We do | You do |
| Where you sign in | `<your-slug>.vantage.hostxtra.co.uk` | Your own hostname |
| Database and backups | Ours | Yours |
| Licence | Installed for you | You paste it in |
| Team members | Granted from Vantage HQ | Created in the instance itself |
| Free tier | Yes, one per account | Yes, one per account |
| Expired Free instance | Eventually deleted, after warning emails | Never deleted |
## Cloud
You create an instance from the HQ portal and it exists a few seconds later,
already licensed. People you grant access to get a real user inside that
instance see [People and roles](../hq/people-and-roles.md) but HQ owns their
password, role and existence.
You create an instance from the Vantage HQ portal and it is ready seconds later,
already licensed. People you grant access to get a real account inside that
instance, but Vantage HQ owns their password and role. See
[People and roles](../hq/people-and-roles.md).
:::info The instance does not phone home
A grant writes a user row into the control plane once. After that the instance
authenticates that person entirely on its own. HQ being down does not stop
anyone signing in to a running instance.
:::
Your instance keeps working whether or not Vantage HQ is reachable. Signing in
and managing servers never depend on it.
Cloud instances on the Free tier are reaped after their licence expires, with
warning emails first. See [Free tier](../hq/free-tier.md).
Cloud instances on the Free tier are deleted some time after their licence
expires, with warning emails first. See [Free tier](../hq/free-tier.md).
## Self-hosted
You run the Docker Compose stack on your own infrastructure. Nothing about the
control plane requires an internet connection to HQ at runtime a licence is a
signed file, verified locally.
You run Vantage with Docker Compose on your own infrastructure. It needs no
connection to us at runtime, because a licence is a signed file your install
checks for itself.
Two ways to get one:
1. **Free** link the install to an HQ account and claim it
([Claim a Free licence](./claim-free-licence.md)).
2. **Paid** buy from HQ, which creates a placeholder, then paste the install's
real instance UUID to bind and issue
([Self-hosted instances](../hq/self-hosted-instances.md)).
1. **Free.** Link the install to a Vantage HQ account and claim it. See
[Claim a Free licence](./claim-free-licence.md).
2. **Paid.** Buy from Vantage HQ, then paste your install's instance ID to have
the licence issued. See
[Self-hosted instances](../hq/self-hosted-instances.md).
Self-hosted users are local (or OIDC). There is no projection from HQ, and the
three member endpoints in HQ refuse to touch a self-hosted instance at all.
People who sign in to a self-hosted install are created in the install itself,
either with a password or through single sign-on. Vantage HQ cannot add them for
you.
## Which should you pick
Pick cloud if you want the thing running now and do not want to own a MongoDB.
Pick cloud if you want it running today and would rather not run a database.
Pick self-hosted if your policy requires the control plane inside your own
network, or the servers you manage cannot reach the public internet.
network, or the servers you manage cannot reach the internet.
Moving between them is a migration, not a switch instances are bound to a
deployment at creation, and a licence binds to an instance UUID.
Moving between the two means migrating your data, and a new licence, since a
licence is tied to one instance.
## Next
- [Self-hosted install](./self-hosted-install.md)
- [Accounts and signup](../hq/accounts-and-signup.md) if you are going cloud
- [Accounts and signup](../hq/accounts-and-signup.md), if you are going cloud
docs/getting-started/first-login.md
+56 -41
View File
@@ -6,67 +6,82 @@ sidebar_label: First login
A fresh install has no users and no instance. The first visit creates both.
## 1. Bootstrap
## 1. Create the first account
Open the control plane in a browser. Because no user exists, you land on
`/setup`.
Open your Vantage address in a browser. Because no user exists yet, you land on
the setup page.
Fill in:
| Field | Notes |
| ------------- | ------------------------------------- |
| Instance name | Display name. Shown throughout the UI |
| Email | Becomes your sign-in identity |
| Password | Stored bcrypt-hashed |
| Field | Notes |
| ---------------- | --------------------------------------------------------- |
| Instance name | Also used to derive your instance's own subdomain |
| Owner email | Becomes your sign-in identity |
| Password | At least 8 characters |
| Confirm password | Must match |
Submitting creates the instance and its **owner** you.
**Setup Instance** creates the instance and makes you its **owner**.
:::warning Bootstrap works exactly once
The endpoint is open only while the database has no users. As soon as the first
one exists, There is no second chance to create the first owner, so record the
credentials before you continue.
:::warning Your instance gets its own address
If you installed on a name like `vantage.example.com`, an instance called Acme
signs in at `acme.vantage.example.com`, and each instance keeps its own sign-in.
Make sure DNS and your reverse proxy cover that subdomain, or use a wildcard.
:::
## 2. Copy the Instance ID
:::warning Setup runs exactly once
It is only available while the database has no users. Once yours exists, the
page closes for good, so record the email and password before you continue.
:::
Once you have finished setup you will see the successfully created page.
## 2. Copy the instance ID
This will show the Instance ID. You will need this ID when creating a license in the HQ.
The confirmation page, headed **Instance created**, shows your instance ID and
your sign-in address. You need that ID to claim a licence in Vantage HQ, and it
is the reference support works from. You can find it again later on the
**Licence** page in the sidebar.
## 3. Sign in
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.
Click **Go to sign in**, then 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:
You land on the servers page, which is empty. The sidebar is the whole product:
| 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 |
| Section | What it does |
| --------------- | ------------------------------------------------ |
| Servers | Your fleet: enrol, inspect, console, update |
| Monitors | HTTP, TCP, ping and certificate checks |
| Vulnerabilities | Known security issues in installed packages |
| Workloads | Containers and services running on your servers |
| SSH Keys | Public keys and which servers they are on |
| Secrets | The encrypted vault |
| Workflows | Compose and run scripted work |
| Steps | The reusable step library |
| Audit Log | A record of everything that changed |
| Licence | Your tier, allowance and expiry |
| Settings | People, sign-in, alerts and integrations |
## 5. Add the rest of your team
**Licence** and **Settings** are shown only to owners and admins.
Go to **Settings → Access**. Add members with a role:
## 5. Install your licence
| Role | Can |
| -------- | -------------------------------------------------- |
| `owner` | Everything, including billing-adjacent settings |
| `admin` | Everything except owner-only settings |
| `member` | Day-to-day work servers, keys, workflows, monitors |
Until a licence is installed, the instance is read-only: you can look, but you
cannot add servers or anything else. Continue with
[Claim a Free licence](./claim-free-licence.md).
Settings and organisation management require `owner` or `admin`.
## 6. Add the rest of your team
If you would rather not manage passwords, configure single sign-on instead: see [Settings](../vantage/settings.md#single-sign-on).
Go to **Settings → Access** and add people with a role:
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.
| Role | Can |
| -------- | ---------------------------------------------------- |
| `owner` | Everything |
| `admin` | Everything except owner-only settings |
| `member` | Day-to-day work: servers, keys, workflows, monitors |
Changing settings, and adding or removing people, needs `owner` or `admin`.
If you would rather not manage passwords, you can use single sign-on instead,
which is available on paid plans. See
[Settings](../vantage/settings.md#single-sign-on).
docs/getting-started/first-server.md
+50 -45
View File
@@ -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)
docs/getting-started/self-hosted-install.md
+65 -54
View File
@@ -4,52 +4,46 @@ title: Install Vantage (self-hosted)
sidebar_label: Self-hosted install
---
This installs the control plane on a host you own. Budget about fifteen minutes.
This puts the control plane on a host you own. Budget about fifteen minutes.
## Before you start
You need:
- A Linux host with **Docker** and the **Compose plugin**.
- A DNS name pointing at it. You will use it for both the web UI and, with a
port, for agents.
- A reverse proxy terminating TLS in front of the web UI. gRPC on `:9090` is
reached directly by agents.
- Two ports reachable from every machine you intend to manage: the web port for
people, and **9090** for agents.
- Outbound access from the control plane, and from every managed machine, to
`gitea.hostxtra.co.uk`, which serves the agent releases.
- A DNS name pointing at that host. People use it for the web UI, and your
agents use it too.
- A reverse proxy in front of Vantage that terminates TLS. It needs to handle
both the web UI and the agent port, `9090`, which speaks HTTP/2.
- Those two ports reachable: the web port from wherever your people are, and
`9090` from every machine you intend to manage.
- Outbound access from the control plane, and from each managed machine, to
`gitea.hostxtra.co.uk`, which serves the agent downloads.
The stack itself brings MongoDB, Redis and guacd with it. You do not need to
provide a database.
The stack brings MongoDB, Redis and the console daemon with it, so there is no
database to provide.
## 1. Get the compose file
Put `deploy/docker-compose.yml` from the repository in a working directory, for
example `/opt/vantage`.
## 1. Get the Compose file
```bash
mkdir -p /opt/vantage/data && cd /opt/vantage
# copy docker-compose.yml here
mkdir -p /opt/vantage && cd /opt/vantage
curl -fsSLO https://gitea.hostxtra.co.uk/mrhid6/vantage/raw/branch/main/deploy/docker/docker-compose.yml
```
The `server` service bind-mounts `./data`, which is where workflow run logs are
written. Create it before first boot so it is not owned by root-in-container in
a way you did not intend.
## 2. Write the environment file
Create `/opt/vantage/.env`:
```bash
# The host:port agents dial. NOT the web URL this port speaks gRPC.
# The host:port your agents connect to. This is not the web URL;
# this port speaks gRPC.
GRPC_HOST=vantage.example.com:9090
# 32 bytes as 64 hex characters. Generate with the command below.
# 32 bytes as 64 hex characters. Generate it with the command below.
KEY_ENCRYPTION_KEY=
# Optional: where workflow run logs are written inside the container.
# The host serving agent downloads.
GITEA_HOST=gitea.hostxtra.co.uk
```
Generate the encryption key:
@@ -58,17 +52,27 @@ Generate the encryption key:
openssl rand -hex 32
```
:::danger Keep the encryption key
`KEY_ENCRYPTION_KEY` encrypts SSH private keys, vault secrets, OIDC client
secrets and console credentials with AES-256-GCM. Lose it and every one of those
becomes unreadable there is no recovery path. Back it up somewhere other than
the server it protects, and never rotate it without a planned re-encryption.
Then make sure the `server` service passes `GITEA_HOST` through, by adding this
line to its `environment:` block in `docker-compose.yml`:
```yaml
GITEA_HOST: ${GITEA_HOST}
```
Without it, the install command you hand to a new server cannot work out which
agent to download.
:::danger Keep the encryption key safe
`KEY_ENCRYPTION_KEY` encrypts SSH private keys, vault secrets, single sign-on
client secrets and console credentials. If you lose it, all of those become
unreadable and there is no way to recover them. Back it up somewhere other than
the server it protects, and do not change it once the install is in use.
:::
:::warning `GRPC_HOST` has no default
The server refuses to boot without it. There is deliberately no fallback to the
web host: that would hand every agent a port that does not speak gRPC, and the
failure would only surface later, on each agent, as a connection error.
The server will not start without it. There is deliberately no fallback to your
web address, because that port does not speak the protocol agents use, and the
mistake would only show up later as every agent failing to connect.
:::
## 3. Start the stack
@@ -78,31 +82,37 @@ docker compose up -d
docker compose ps
```
Five services come up: `mongo`, `redis`, `guacd`, `server` and `web`.
Five services start: `mongo`, `redis`, `guacd`, `server` and `web`.
Check the server got through boot:
Check the server got through startup:
```bash
docker compose logs -f server
```
Boot runs database migrations, builds indexes and seeds the default workflow
step library. Index builders for auth and settings are **fatal on failure** —
they enforce tenant isolation, so the server would rather not start than start
without them.
On first boot it prepares the database and loads the built-in workflow step
library. If it stops during that, it will say why, and it is meant to stop
rather than run in a half-prepared state.
## 4. Put a proxy in front
Point your reverse proxy at `web` on port `3000` and terminate TLS there. The
web app calls the REST API through a Next rewrite, so you do not need to expose
`8080` publicly.
web app reaches the API internally, so there is no need to publish port `8080`.
Do **not** proxy `9090`. Agents connect to it directly over TLS.
Agents connect to port `9090`. Vantage does not terminate TLS itself, so put
that port behind your proxy too, with a certificate valid for the name in
`GRPC_HOST`. The proxy must speak HTTP/2 through to Vantage. Many do not do so
by default, and the symptom is agents that register once and then stop
responding.
For a private network where TLS is not required, you can instead set
`tls: false` in each [agent's config](../reference/agent-config.md) and let
agents reach the port directly.
## 5. First sign-in
Open your hostname in a browser. With no users in the database, you are sent to
`/setup`.
Open your hostname in a browser. With no users in the database yet, you are sent
to the setup page.
Continue with [First login](./first-login.md).
@@ -113,23 +123,24 @@ Continue with [First login](./first-login.md).
| `docker compose ps` | five services `running` |
| `curl -s localhost:8080/auth/bootstrap-status` | JSON saying bootstrap is needed |
| `nc -z your-host 9090` | open |
| `docker compose logs server \| grep -i fatal` | nothing |
| `docker compose logs server` | no fatal errors |
## Common install problems
**Server exits immediately.** Almost always a missing `GRPC_HOST`. The log line
**The server exits immediately.** Almost always a missing `GRPC_HOST`. The log
names it.
**Agents register but never go active.** They reached `:9090` for `Register` but
cannot sustain the poll, or `GRPC_HOST` names a host they resolve differently.
Check from the managed machine, not from the control plane host.
**Agents register but never go active.** They reached port `9090` once but
cannot hold the connection, or your proxy is not passing HTTP/2 through. Test
from the managed machine, not from the control plane host.
**Secrets pages error.** `KEY_ENCRYPTION_KEY` is empty or not 64 hex characters.
**Secrets pages show an error.** `KEY_ENCRYPTION_KEY` is empty or is not 64 hex
characters.
More in [Troubleshooting](../reference/troubleshooting.md).
## What this install does not include
## What is not included
The website, the HQ portal and this documentation site are hosted by us and are
not part of a self-hosted install. It deliberately runs none of them, and in
particular never holds the licence signing key.
The marketing site, the Vantage HQ portal and this documentation site are hosted
by us. A self-hosted install runs none of them, and it never holds the key that
signs licences.
docs/getting-started/what-is-vantage.md
+29 -36
View File
@@ -5,59 +5,52 @@ sidebar_label: What is Vantage
---
Vantage manages a fleet of servers from one place. It began as SSH key
management and grew outwards: key assignment, scripted workflow execution,
service monitoring, a secrets vault, a browser-based console and OS update
management.
management and grew outwards: key assignment, scripted workflows, service
monitoring, a secrets vault, a browser console and OS update management.
## The pieces
```mermaid
flowchart TD
W["Web UI<br/>servers · keys · workflows · monitors<br/>secrets · audit · console · settings"]
S["Server<br/>REST :8080 · gRPC :9090<br/>MongoDB · Redis · guacd"]
S["Vantage server<br/>the control plane"]
A["Agent<br/>one per managed server<br/>Linux and Windows"]
W -->|REST, cookie session| S
S -->|gRPC over TLS| A
A -.->|outbound only| S
W -->|you sign in here| S
S -->|sends work| A
A -.->|connects outbound| S
```
**The server** holds all state and does all decision-making. It exposes a REST
API on `:8080` for the web UI and a gRPC API on `:9090` for agents. MongoDB
stores everything durable; Redis stores sessions and nothing else.
**The server** is the control plane. It holds all your data and makes all the
decisions.
**The agent** is a single Go binary running as root on each managed server. It
polls the control plane every 30 seconds for desired key state, and holds a
bidirectional command stream so the server can push work run a workflow step,
generate a key, apply updates without waiting for the next poll.
**The agent** is a single small program running on each managed server. It asks
the control plane what it should be doing, and holds an open connection so
Vantage can send it work without waiting.
**The web UI** is the operator interface. Everything it does goes through the
REST API, which is the actual security boundary; the UI only ever makes things
convenient.
**The web UI** is what you use. Everything it can do goes through the same API
that enforces your permissions, so nothing is possible in the UI that would not
be permitted elsewhere.
## How agents connect
The agent dials **out** to the control plane. There is no inbound listener on a
managed server, no port to open and no NAT traversal to arrange. If the machine
can reach your Vantage host on the gRPC port, it can be managed.
The agent always connects **outbound**. There is no listener on a managed
server, no port to open and no NAT to work around. If the machine can reach your
Vantage address, it can be managed.
That direction is why `GRPC_HOST` exists as an explicit setting: the agent has
to be told a `host:port` it can reach, and there is no safe default the server
could guess on its behalf.
That is why you tell Vantage its own agent address (`GRPC_HOST`) when you install
it: the agent has to be given an address it can reach, and Vantage cannot guess
one for you.
## Two request patterns
## Keeping things current
| Pattern | Used for | Why |
| ----------------------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Poll, every 30s | desired SSH key state | Key changes are not urgent, and polling survives a dropped connection with no reconnection logic |
| Push, over the command stream | workflow steps, key generation, updates, agent self-update | Clicking Run should not wait up to 30 seconds |
## Multi-tenancy
Every document in the database carries an instance ID, and every query is scoped
by it. One deployment can therefore host many independent tenants. On a
self-hosted install that mechanism is still there you simply have one tenant.
| What | How it works |
| ------------------------- | ------------------------------------------------------------------------- |
| SSH keys on a server | The agent checks every 30 seconds and only writes when something changed |
| Workflow steps, updates | Sent to the agent straight away, so clicking Run does not wait for a check |
| Inventory | Reported every 30 seconds, with a fuller snapshot every 15 minutes |
| Pending OS updates | Checked hourly |
## Next
- [Cloud or self-hosted](./cloud-vs-self-hosted.md) which one you want
- [Self-hosted install](./self-hosted-install.md) stand it up
- [Cloud or self-hosted](./cloud-vs-self-hosted.md), to pick which one you want
- [Self-hosted install](./self-hosted-install.md), to stand it up