Installing the control plane

The control plane runs in Docker on a single machine. It does not have to be a large one — it schedules and watches; the databases live on the servers you enrol from it. Two cores and 2 GB is enough to start.

The command

curl -fsSL https://quorumkit.subhamsaha.in/get | sudo sh

It needs root, because it installs system-wide. If you run it without, it stops and prints the sudo line to use — including any variables you had set, since sudo discards assignments placed before it.

What it does, in order

Installs Docker, if the host has none. Using Docker's own convenience script, not a reimplementation of it. Set QK_INSTALL_DOCKER=0 to refuse this and install Docker yourself first.

Writes /opt/quorumkit — a compose file, an .env holding generated secrets, and Traefik's dynamic configuration. Nothing else on the host is touched.

Pulls the images and starts the stack. PostgreSQL for the control plane's own state, and quorumkitd itself.

Waits for the console to answer, then prints its address and the password it generated.

What "curl | sh" is fetching

Worth being precise about, because you are about to run it as root.

The script is plain text on a web server. curl downloads it, sh runs it. It carries no product — it writes configuration and starts containers. QuorumKit itself arrives as container images, which Docker pulls separately. Read it before you run it if you like; that is the whole point of it being one file:

curl -fsSL https://quorumkit.subhamsaha.in/get | less

Signing in

The installer prints both halves:

Console   http://203.0.113.10:8080
Sign in   admin@localhost / <generated>

The address is IP and port until you point a domain at the host — publishing a name that does not resolve yet would be worse than publishing one that works. The password is generated per install and stored in /opt/quorumkit/.env; quorumkit password prints it again.

Adding a domain

Point an A record at the host, then:

quorumkit set-domain panel.example.com you@example.com

That starts Traefik, requests a Let's Encrypt certificate over HTTP-01, and rewrites the console's public URL. Until you run it, no proxy runs at all — there is nothing for one to do.

What it rewrites

QK_PUBLIC_URL and QK_GRPC_ADVERTISE in /opt/quorumkit/.env, and Traefik's dynamic configuration. The gRPC advertise address is the one agents dial, and it becomes a subject-alternative name on the gateway certificate — which is why changing it is a command rather than an edit.

If the certificate does not issue

HTTP-01 needs port 80 reachable from the internet and the A record already resolving. quorumkit logs traefik says which of the two is missing. The console stays reachable on its IP and port throughout; a failed certificate does not take the installation down.

Options

Set these before the command. After sudo, not before it.

Variable	Default	What it changes
`QK_VERSION`	`latest`	The image tag to install. Pin it for a reproducible install.
`QK_DIR`	`/opt/quorumkit`	Where the compose file and secrets are written.
`QK_ADDRESS`	detected	The address agents dial. Set it if the host has several.
`QK_REGISTRY`	`ghcr.io/subhamsaha9`	Where images are pulled from.
`QK_INSTALL_DOCKER`	`1`	`0` refuses to install Docker.
`QK_CHANNEL`	the public channel	Where the installer, the compose file and release news come from. A directory works as well as a URL, which is what an air-gapped install uses.

Whatever QK_CHANNEL was set to is recorded in .env, so the console checks the same place the host was installed from rather than a URL it may not be able to reach. See Updating.

Running it again

Re-running upgrades the images. Every secret, the control-plane database and the certificate authority stay exactly where they were — quorumkit update is the same script, and so is the Update button in the console (Updating).

Back the certificate authority up. Every agent's identity is signed by it, and losing it orphans the whole fleet: quorumkit backup.

Managing it afterwards

The installer leaves a quorumkit command on the host.

Everyday

quorumkit status              # what is running
quorumkit logs                # follow the control plane's log
quorumkit logs postgres       # or any other service
quorumkit restart
quorumkit start / stop

Upgrading

quorumkit update

The same script the install used. Images are pulled and the stack restarted; data, secrets and the certificate authority are untouched.

You do not have to be logged in to the host for this. The console tells you when a newer release exists and can apply it for you — see Updating.

Credentials and backups

quorumkit password            # print the admin password again
quorumkit backup              # archive the CA and secrets

Installing the control plane

On this page