Documentation

3.1.1 Service Inventory

The component reference in 1.1.7 lists what each service does. What follows adds the operational detail an administrator needs: how each service is started and stopped, what it depends on, and what breaks when it is down.

CBOM-Server: the portal and API. Depends on MongoDB and Keycloak. When down, the portal and all read APIs are unavailable, but ingestion continues and no data is lost.
Collector-Services: ingestion. Depends on MongoDB. When down, sensors cannot submit; file-based emitters buffer and retry, HTTP emitters fail. Nothing in the portal breaks.
Deployment and discovery servers: scan execution. When down, scheduled and manual scans do not run; existing data is unaffected.
MongoDB: all persistent state. When down, everything is down.
Keycloak: authentication. When down, existing sessions continue until expiry but no new login succeeds, which makes a Keycloak outage look intermittent.
Observability pipeline: logging only. When down, the platform runs normally but operators lose visibility, which is precisely when they need it.

3.1.2 Start, Stop and Status

Container deployment: bring the stack up or down with Compose, and restart an individual container by name. Restarting a single service is safe and is the normal response to a configuration change.
Native deployment: use the shipped start and stop helpers for the whole stack or a single named service, or the supervised units if the deployment wraps services in them.
Check status per service and confirm the version endpoint responds before declaring a restart successful. A container in a running state is not the same as a service that is serving.

3.1.3 Startup Order and Dependencies

MongoDB and Keycloak must be ready before CBOM-Server starts. CBOM-Server performs its database connection, schema seeding and index creation at startup and does not defer them.
Collector-Services requires only MongoDB.
The frontend and proxy can start at any point but will serve errors until the backends are up.
The observability pipeline should start early so that startup problems in other services are captured.
After a full platform stop, start in the order: database, identity provider, backends, frontend and proxy.

3.1.4 Service Control Commands

The sections above describe what each service is and what depends on it. These are the commands.

Container deployment

docker compose up -d                      # start everything
docker compose up -d --build              # rebuild images, then start
docker compose down                       # stop, keep data volumes
docker compose down -v                    # stop and DELETE data volumes
docker compose restart cbom-server        # restart one service
docker compose up -d --force-recreate cbom-server   # recreate one service
docker compose ps                         # status
docker compose logs -f --tail=100 collector-worker

! docker compose down -v deletes the database volume. It removes the inventory, the audit trail, the configuration and the identity provider's own data. It is the right command for tearing down an evaluation and the wrong one everywhere else. There is no undo and no prompt.

Restarting one service is the normal response to a configuration change and is safe. The one consequence worth knowing: restarting the backend signs out everyone it was serving, because sessions are held in memory by the process that created them.

Native deployment

./start.sh                      # everything
./start.sh cbom                 # backend API
./start.sh collector            # collector
./start.sh collector-worker     # the queue consumer
./start.sh ai                   # AI service
./start.sh frontend             # console

./stop.sh                       # everything
./stop.sh cbom                  # one service, same names

The start script runs pre-flight checks before starting anything — database reachability in particular — so a failure to start is usually reported as the missing dependency rather than as a stack trace from the service.

Where the deployment wraps services in supervised units, use those instead; the scripts and the units will fight over the same process otherwise.

Confirming a restart worked

curl -fsS https://cbom.example.com/cbomsrv/api/v1/version

A container in the running state is not a service that is serving. The version endpoint is the same check the platform's own health check performs, so if it answers, the service is genuinely up.

3.1.5 Starting After a Full Stop

The dependency rules are in 3.1.3. As an ordered checklist:

Database
Message broker
Identity provider
Backend API, collector, collector worker
Console, AI service, proxy

In a container deployment this is handled for you — nothing starts until what it depends on reports healthy. The order matters when services are started by hand.

3.1.6 Restarting After a Configuration Change

Changed	Needs
A setting in System Configuration	Nothing — configuration is reloaded, and a restart can be triggered from the console where one is needed
A value in the environment file	`docker compose up -d` to recreate the affected services
The console's backend URL	A rebuild — it is compiled in: `docker compose up -d --build frontend`
The TLS certificate	A proxy reload: `docker compose exec nginx nginx -s reload`
The authorisation mode	A backend restart. It is deliberately not editable from the console

A section hand-edited into a configuration file does not survive. The YAML files are generated from the database on every configuration save, activation and startup, and the regeneration is wholesale — it writes what the database says and nothing else, with nothing logged about what was removed. Change settings in System Configuration, not in the files.

3.1.7 Planned Maintenance

Taking the platform down cleanly:

Let running discovery tasks finish, or accept that agents will spool and republish.
Stop the application services, leaving the database and broker running.
Do the work.
Start the application services.
Confirm with the version endpoint and one small discovery run.

Agents need no coordination. An agent whose platform is unavailable writes its results to its own disk and republishes when the platform returns. This is what makes maintenance an ordinary operation rather than a scheduled outage with a notice to every target owner.

A multi-node tier can be done without an outage — drain one node, restart it, return it, repeat. The procedure is in High Availability Runbooks.

3.1.8 Scheduled Background Work

Several things run on their own without an operator:

Job	Cadence	What it does
Session cleanup	Every 30 seconds	Removes expired sessions
Deduplication	After ingestion	Consolidates raw results into materials
Stalled scan sweep	Every 15 minutes	Completes scans that went quiet
Retention expiry	Continuous	Expires audit and notification records past their retention
Integration sync	Per integration	Pulls from the configured third-party source

None needs starting, and none should be scheduled separately. If one appears not to be running, the symptom is usually visible elsewhere first — a growing deposit backlog for deduplication, records past their retention for expiry.

CBOM Secure

3.1 Managing Services