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

​
The compose file

The file brings up Postgres and the Hoop image started in control plane mode, plus an optional Sidecar and a database for it to sit in front of. The subcommand picks the mode: the same image runs the gateway when it is started with hoop start gateway. The Control Plane publishes one port, 8009. It opens no gRPC transport and starts no protocol proxies, so there is nothing else to expose. The Sidecar is behind a profile because its token does not exist until the Control Plane issues one, and a Sidecar without a token exits rather than retrying. Profiles are additive, so docker compose up brings up Postgres and the Control Plane and nothing else.

​
Run it on your machine

Open http://localhost:8009 in your browser.
Confirm you got the mode you asked for:
To run it on a host your Sidecars can reach, follow the section below instead.

​
Add a Sidecar

1

Create the first account

At http://localhost:8009. Authentication is local by default, so there is nothing to wire up first.
2

Register a Sidecar

Create one named appdb-sidecar and copy the hsc_ token. It is shown once.
3

Put the token in .env

.env
4

Bring it up

The Control Plane holds no configuration for this Sidecar yet, so the first handshake answers 412 and the Sidecar imports the document the compose file carries. The log says configuration imported into the control plane, and the Sidecar appears in the fleet with a recent check-in.
5

Try it

CREATE TABLE goes through. The DROP comes back as FATAL: destructive statements are not permitted through this lane — the one guardrail the compose file ships with.From here, edit the configuration in the Control Plane. The local file has done its job; on the next start its listeners are ignored with a warning rather than merged. See Connect a Sidecar.

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