Skip to main content
The fastest way to get a Control Plane running. Good for evaluation, and good enough for a single-host production install.

​
Supported operating systems

Linux

Tested on Ubuntu 24.04 and Amazon Linux 2.

MacOS

Intel and Apple Silicon (M1/M2).

​
Required tooling

1

Docker

Install or update to Docker 20.10.0 or greater.

Install Docker for Linux

Install Docker for MacOS

2

Docker Compose

Install or update Docker Compose to 2.11.x or greater.
Run docker compose version to check which version you have installed.

Install Docker Compose for Linux

It ships with the Docker engine, but a standalone installation also works.

Docker Compose for MacOS

Nothing to install — it comes with Docker Desktop.

​
Run it on your machine

No configuration needed. This runs everything on localhost:
Open http://localhost:8009 in your browser. To run it on a host your Sidecars can reach, follow the section below instead.

​
Run it on a remote machine

1

Download the compose file

2

Write the .env file

The Control Plane needs to know its own public address, so it can serve the web app assets and tell Sidecars where to come back to.
The .env file must sit next to docker-compose.yml.
.env
Every other setting is optional — see Environment Variables for the full list.
If you cannot reach the web app from outside the VM, check your firewall rules and make sure TCP/8009 is open or bound so it is reachable from your network.
3

Run

The first run pulls the images, so it can take a few minutes.
4

Manage the containers

Follow the logs:
Stop everything:
5

Sign in

Visit http://<vm-public-dns>:8009 and create the first account. Authentication is local by default: the Control Plane manages users and passwords itself and signs its own access tokens, so there is nothing else to wire up before you can log in.

​
Troubleshooting

​
Assets fail to load behind a domain

API_URL defaults to 127.0.0.1, which only works from inside the VM. In production it has to carry the full scheme and host:
Two things go wrong most often:
  • Scheme omitted. yourdomain.com is not enough — assets are served with the scheme from this value.
  • An IP behind DNS forwarding. If you set an IP and later put a domain in front of it, the assets still point at the IP. API_URL has to be the domain users actually reach.

​
Next

Connect a Sidecar

Issue a token, point a Sidecar at the server host, and confirm it picked up its configuration.