---
id: self-hosted-install
title: Install Vantage (self-hosted)
sidebar_label: 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

```bash
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`:

```bash
# 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:

```bash
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`:

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

```bash
docker compose up -d
docker compose ps
```

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

Check the server got through startup:

```bash
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](../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 yet, you are sent
to the setup page.

Continue with [First login](./first-login.md).

## 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](../reference/troubleshooting.md).

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