Step 2: Run ControlBird CE

Start the ControlBird CE stack with Docker Compose.

Docker
2
Run
3
Access
4
Architecture
5
Explore
6
Connect
7
Automate
8
History
9
Alarms
10
Users
11
Access+
12
Scripts
13
Logs
14
Dashboards
15
Builders
16
Kiosks
17
Themes
18
Config
19
Audio
20
Failover
21
Email

Start ControlBird

ControlBird CE runs as a stack of containers managed by Docker Compose. Download the Compose file from controlbird.io, then start the stack. The images are pulled if they are not already cached:

curl -fsSLO https://controlbird.io/compose.yaml docker compose up -d

What This Does

docker compose up -d starts one container for each part of ControlBird and runs them in the background:

gatewayWeb UI over HTTP on port 3000 and over HTTPS on port 3443. Keep the host port at 3443, since links that move a browser to HTTPS name that port.
kernelThe Store, persisted in a Docker volume so your data survives restarts
loggerCollects the logs of every container and keeps them in a Docker volume
config-managerKeeps the history of your configuration in a Docker volume
alarmRaises and tracks alarms
certificate-managerCreates and renews certificates
extension-managerInstalls and upgrades extensions
plugin-engineRuns your scripts
session-managerManages user sessions
runtime-service-managerStarts and supervises the containers of the extensions you install
cluster-paramsRuns once at start to prepare the node's configuration, then exits
initRuns once at start to apply that configuration before the other services start, then exits

Why the kernel port is not published

The containers reach the kernel on the stack's own private network, so a single node needs no published port for it.

Publish it only if you are running several nodes that peer with each other, by adding a ports entry for 9100:9100 to the kernel service. Even then, only do it on a network you trust. Anything that can reach that port can read and write the whole store, so it should never face the public internet.

HTTPS and the Node Certificate

On first start the node creates its own self-signed certificate and serves the web UI over HTTPS on port 3443 alongside plain HTTP on port 3000. Because no public certificate authority signed it, your browser warns the first time you open https://<host>:3443. To remove the warning, trust the node's own certificate:

  1. Sign in, open Certificate Manager, select the Web Server tab, and select Download node certificate.
  2. Install the downloaded file as a trusted certificate on each computer or phone that opens the node, using that operating system's certificate settings.

The certificate names localhost and the gateway container's own host name and addresses, which differ from your computer's. A browser also checks that the address you type is named in it, so tell the node the names and IP addresses you will use to reach it with CB_PUBLIC_HOSTNAME, a comma-separated list, before its first start:

CB_PUBLIC_HOSTNAME=controlbird.lan,192.168.1.10 docker compose up -d

The node reads CB_PUBLIC_HOSTNAME when it creates its certificate. On a node that already has one, create or import a certificate that names your addresses in Certificate Manager and choose it on the Web Server tab instead.

The certificate is valid for 825 days. About 30 days before it expires, the node replaces it with a new one and shows a low-priority alarm for a week. Download and install the new certificate when that happens. To serve a certificate from your own CA or a public one instead, or to switch to HTTPS only, see Web Server in the Certificate Manager guide.

Connecting the Command-Line Tools

The ControlBird command-line tools, such as cb-cli, run from their own images and connect to https://<host>:3443 with an API key you create after signing in and the node certificate you downloaded above. See Connecting to a Community Edition node for the full commands.

Servers Inside Integrations

Integrations that act as servers, such as the MQTT broker, the OPC UA server, and the Modbus TCP server, run in their own containers on the stack's private network. The stack does not publish their ports to the host. Integrations that connect out to your devices work as before.

In-Memory Store

CE keeps entity and field data in memory for sub-millisecond reads. Every change is recorded in a write-ahead log and captured in snapshots in the data volume, so your data survives a restart of the stack. Memory use grows with your data, so leave headroom when running on a small host like a Raspberry Pi.

Verify It's Running

Check that the containers are up:

docker compose ps

Every service should show running, except cluster-params and init, which exit once they finish. The web UI takes a few seconds to initialize on first start.

Managing the Stack

Stop

docker compose stop

Start Again

docker compose start

View Logs

docker compose logs -f gateway

Name any service in place of gateway, or none for all of them.

Remove

docker compose down

Your data is safe in the stack's Docker volumes. Uninstall your extensions in the web UI first, because Docker Compose does not remove the containers ControlBird started for them.