4.3 KiB
id, title, sidebar_label
| id | title | sidebar_label |
|---|---|---|
| self-hosted-install | Install Vantage (self-hosted) | Self-hosted install |
This installs 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
:9090is 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.
The stack itself brings MongoDB, Redis and guacd with it. You do not need to provide a database.
1. Get the compose file
Put deploy/docker-compose.yml from the repository in a working directory, for
example /opt/vantage.
mkdir -p /opt/vantage/data && cd /opt/vantage
# copy docker-compose.yml here
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:
# The host:port agents dial. 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.
KEY_ENCRYPTION_KEY=
# Optional: where workflow run logs are written inside the container.
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.
:::
:::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.
:::
3. Start the stack
docker compose up -d
docker compose ps
Five services come up: mongo, redis, guacd, server and web.
Check the server got through boot:
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.
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.
Do not proxy 9090. Agents connect to it directly over TLS.
5. First sign-in
Open your hostname in a browser. With no users in the database, you are sent to
/setup.
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 | grep -i fatal |
nothing |
Common install problems
Server exits immediately. Almost always a missing GRPC_HOST. The log line
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.
Secrets pages error. KEY_ENCRYPTION_KEY is empty or not 64 hex characters.
More in Troubleshooting.
What this install does not include
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.