2.3 Container Installation (Docker Compose)
2.3.1 Overview
The whole stack is launched by Compose on a private container network. Only the reverse proxy publishes a host port. Configuration files are generated from templates on every container start by each service entrypoint, using values from a single environment file — so configuration is edited in one place and never inside a running container.
2.3.2 Pre-Setup
Initialise the sensor library component recursively.
Run the setup helper. It copies the environment template to its working filename, generates evaluation TLS certificates, and warns if the identity provider realm export is absent.
Fill in every placeholder secret in the environment file. The helper deliberately leaves them as obvious placeholders rather than generating them, so that an unset secret fails visibly.
Place the identity provider realm export, if migrating from an existing instance.
2.3.3 Environment Variables
The environment file carries the full variable reference. The minimum set that must be changed before first start is:
Database root password and application database password.
-
Application secret key: a high-entropy random value, not a memorable string.
Identity provider client secret and administrator password.
-
Frontend URL and backend URL: both must use the external FQDN chosen in 2.2.6.
Log pipeline endpoint.
Log dashboard administrator password.
-
Credential encryption key: this must be a valid key for the encryption scheme in use, not an arbitrary string. An invalid key does not fail at startup; it fails the first time a credential is written, which is much later and much harder to diagnose. Generate it with the documented helper.
2.3.4 Build and Start
Build and start the stack with a single Compose command.
On first start, a one-shot seeding container loads the initial data set — default policies, widget definitions, dashboard templates and reference data. It runs once and exits; a non-zero exit here means the platform will come up with an empty dashboard, so check it.
The platform registers sensor schemas at startup, which is what populates the sensor list in the template builder.
Bring the stack down with the corresponding Compose command. Bringing it down without removing volumes preserves all data; removing volumes destroys it.
2.3.5 Volume and Persistence Map
Two categories of storage exist, and they behave differently. The distinction matters, because editing the wrong copy of a file is the most common configuration mistake in a container deployment.
-
Host-bind mounts: operator-editable files on the host, mounted read-only into containers. These are the configuration templates and certificates, the proxy configuration, the identity provider realm export, and the observability pipeline configuration. Edit these on the host; no image rebuild is needed, only a container restart.
-
Named volumes: runtime-managed persistent data. These are the database contents, per-service log directories, the collector per-host certificate cache, the runtime task definitions, the log store, and the log dashboard database. These are what a backup must cover.
Nothing else is persistent. Configuration is regenerated from templates on every container start, frontend assets are rebuilt at image build time, and the identity provider realm is imported on first start only.
2.3.6 First-Boot Sequence
The expected startup order is below. Knowing it makes it possible to identify which step a stalled first boot is actually on.
Database starts and becomes ready.
Identity provider starts and imports the realm, if an export was supplied.
Seeding container loads initial data, then exits.
CBOM-Server starts, reads both configuration files, connects to the database, registers sensor schemas, and ensures its indexes.
Collector-Services starts and reads its configuration.
Frontend and proxy start.
Observability pipeline starts and begins receiving logs.
Platform is reachable at the external FQDN. Log in with the seeded administrator account and change its password immediately.