vantage-docs/docs/getting-started/self-hosted-install.md

id, title, sidebar_label

id	title	sidebar_label
self-hosted-install	Install Vantage (self-hosted)	Self-hosted install

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 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 brings MongoDB, Redis and the console daemon with it, so there is no database to provide.

1. Get the Compose file

mkdir -p /opt/vantage && cd /opt/vantage
curl -fsSLO https://gitea.hostxtra.co.uk/mrhid6/vantage/raw/branch/main/deploy/docker/docker-compose.yml

2. Write the environment file

Create /opt/vantage/.env:

# 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 it with the command below.
KEY_ENCRYPTION_KEY=

# The host serving agent downloads.
GITEA_HOST=gitea.hostxtra.co.uk

Generate the encryption key:

openssl rand -hex 32

Then make sure the server service passes GITEA_HOST through, by adding this line to its environment: block in docker-compose.yml:

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 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

docker compose up -d
docker compose ps

Five services start: mongo, redis, guacd, server and web.

Check the server got through startup:

docker compose logs -f server

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

Terminate TLS at your reverse proxy and route one hostname to two backends:

Path	Backend
/api, /auth, /public, /install, /install.ps1, /update, /update.ps1	server:8080
everything else	web:3000

Both rules are required. The web app forwards nothing to the API, so a proxy that sends the whole hostname to web:3000 serves the interface and answers 404 to every request it makes — starting with the login form.

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 and let agents reach the port directly.

5. First sign-in

Open your hostname in a browser. With no users in the database yet, you are sent to the setup page.

Continue with First login.

Verifying the install

Check	Expected
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	no fatal errors

Common install problems

The server exits immediately. Almost always a missing GRPC_HOST. The log names it.

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 show an error. KEY_ENCRYPTION_KEY is empty or is not 64 hex characters.

More in Troubleshooting.

What is not included

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.