Installing the centre

:::note Placeholder page Flags and defaults below are taken from the centre binary's source as of a recent build. They will drift as the product moves — treat centre --help on the binary you actually run as the source of truth, and this page as a convenience copy of it. :::

There is no configuration file. Everything is a command-line flag.

1. Provide a database

The centre stores desired state, inventory and job history in PostgreSQL. Create an empty database and a role the centre can connect as, then pass the connection string as a DSN.

2. Run the centre binary

./ballast-centre \
  -db "postgres://ballast:password@localhost:5432/ballast?sslmode=disable" \
  -listen 0.0.0.0:9443 \
  -rest-listen 0.0.0.0:8080 \
  -advertise centre.example.internal

Flag	Default	Purpose
-db	(none)	PostgreSQL DSN. Omitted entirely, the centre falls back to an in-memory store — nothing survives a restart. Development only.
-listen	127.0.0.1:9443	Address the gRPC service (agent channel) binds to.
-rest-listen	127.0.0.1:8080	Address the REST API and console bind to. Empty disables the console.
-advertise	(none)	Address agents should dial back on. Required whenever the bind address is not what agents can reach.
-auth	true	Authentication for the console/REST API.
-tls	true	Mutual TLS on the agent gRPC channel.
-rest-tls	false	HTTPS on the console/REST listener. Browsers trust it once they import /ca.crt.
-agent-binary	(off)	Serves the agent installer at /agent/ballast-agent.exe so hosts can fetch it directly from the centre.
-iso-dir	(none)	Directory backing the ISO library.
-guacd	(none)	Address of a guacd instance, enabling the interactive VM console in the browser. Pair with -console-secret naming the stored credential to use.

3. First sign-in

Browse to the REST/console listener address. The first visit lets you set the initial administrator password — there is no default credential and no separate token step.

4. Certificates

With -tls at its default of true, the agent channel uses mutual TLS. On first run without existing certificates, the centre generates a CA and issues itself a server certificate. Agents are issued their own certificate during agent installation.

Certificate lifetime, renewal behaviour, and where the CA private key is stored are TBC — they will be documented here once confirmed, because they decide what a backup of the centre actually needs to include.

Running as a service

Guidance for running the centre binary under systemd (Linux) or as a Windows service will be added here once the packaged install path is finalised.