Startup Options & Deployment

Configure the broker before it starts

Pass configuration at process start so containers, packages, and CI pipelines come up the same way every time. Typical jobs:

Point the data directory at a persistent volume
Import broker or user JSON on first boot
Load a LoT notebook project from git or disk
Install a license file before MQTT accepts connections

Think of startup options as a recipe card. You tell the broker where its data lives and which project to load; it applies that recipe and then stays up as a service or container.

For install commands (Docker, APT, DNF, Windows), start with Installation. For COREFLUX_* variables, secrets, and .env files, see Environment Variables & Secrets.

Command-line options

Configuration

Option	Long form	Description
`-c`	`--config`	Path to broker configuration JSON. Applied only when no broker config exists yet, unless you also pass `--config-force`.
`-cf`	`--config-force`	Overwrite existing broker configuration with `--config`.
`-u`	`--users`	Path to users JSON. Applied only when no users file exists yet, unless you also pass `--users-force`.
`-uf`	`--users-force`	Overwrite existing users with `--users`.
`-p`	`--path`	Data directory (same role as `COREFLUX_DATA_PATH`). Prefer the environment variable so the path is set before `--config` is applied.

Set COREFLUX_DATA_PATH or CONFIG_PATH in the process environment, then start the binary. -p / --path is applied late in startup, so --config can write into the default data directory instead of the path you intended.

Projects and licenses

Load LoT (Language of Things) from a project (git URL, local folder, or a project already stored on this broker). That is the supported way to ship Actions, Models, Routes, and Rules at boot.

Option	Long form	Description
	`--project`	Load a project at startup (git URL, local path, or existing project name).
	`--branch`	Git branch or tag to check out with `--project`.
`-loadLicense`	`--load-license`	Copy a license file into the data directory so the broker can validate it on start.
`-showInstanceKey`	`--show-instance-key`	Print the instance key to stdout and exit (needed to request a license). Does not start MQTT.

A project loaded with --project (or -loadProject at runtime) is remembered across restarts. On the next start, if you do not pass --project, the broker re-activates that project. -unloadProject clears it. --project always wins over the remembered project.

Other options

Option	Long form	Description
`-I`	`--install`	Register a Windows service or a Linux systemd unit for a portable (zip/tarball) binary. Skip this when you installed from APT/DNF — the package already ships `coreflux-broker.service`.
`-h`	`--help`	Display help.

Basic usage

Starting with configuration files

Linux
Windows

# Start with broker configuration
./CorefluxMQTTBroker --config /path/to/broker-config.json

# Start with users configuration
./CorefluxMQTTBroker --users /path/to/users.json

# Start with both
./CorefluxMQTTBroker \
    --config /path/to/broker-config.json \
    --users /path/to/users.json

# Start with broker configuration
.\CorefluxMQTTBroker.exe --config C:\config\broker-config.json

# Start with users configuration
.\CorefluxMQTTBroker.exe --users C:\config\users.json

# Start with both
.\CorefluxMQTTBroker.exe `
    --config C:\config\broker-config.json `
    --users C:\config\users.json

Force overwrite existing configuration

By default, if configuration already exists in the data directory, startup JSON is ignored. Use force flags to overwrite:

# Force overwrite broker config
./CorefluxMQTTBroker --config /path/to/broker-config.json --config-force

# Force overwrite users config
./CorefluxMQTTBroker --users /path/to/users.json --users-force

# Force overwrite both (short form)
./CorefluxMQTTBroker -c /path/to/broker-config.json -cf -u /path/to/users.json -uf

Force flags overwrite existing configurations. Back up your current configuration before using them.

Loading a project at startup

# From git URL
./CorefluxMQTTBroker --project https://github.com/org/my-iot-project.git --branch production

# From local path
./CorefluxMQTTBroker --project /path/to/my-project

# By project name (already stored on this broker)
./CorefluxMQTTBroker --project my-iot-project

Package Actions, Models, Routes, and Rules in a LoT notebook project and load it with --project. That is the supported bootstrap path for LoT at startup.

Configuration files

Broker configuration (JSON)

The broker configuration file defines MQTT service settings:

{
  "Name": "MyCorefluxBroker",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 5443,
  "BindIPForMQTT": "0.0.0.0",
  "BindIPForMQTTwithTls": "0.0.0.0",
  "BindIpForWebSockets": "0.0.0.0",
  "BindIpForWebSocketsTls": "0.0.0.0",
  "AnonymousLogin": false,
  "FullDebugLog": false,
  "ServerCertificatePath": "/path/to/certificate.pfx",
  "ServerCertificatePassword": "your-certificate-password",
  "ResendRetainTopics": false
}

For every supported field (ports, TLS/mTLS, sessions, performance, data paths, ops, durability), see Broker Configuration.

Users configuration (JSON)

The users configuration file defines MQTT users and their permissions:

[
  {
    "UserName": "root",
    "Password": "your-secure-password",
    "AllowedBaseTopic": "#",
    "AllowedSystemConfiguration": true,
    "AllowedUserManagement": true,
    "AllowedLogManagement": true
  },
  {
    "UserName": "device-user",
    "Password": "device-password",
    "AllowedBaseTopic": "devices/",
    "AllowedSystemConfiguration": false,
    "AllowedUserManagement": false,
    "AllowedLogManagement": false
  }
]

Property	Type	Description
`UserName`	string	MQTT username
`Password`	string	MQTT password
`AllowedBaseTopic`	string	Topic access restriction (`#` for all topics)
`AllowedSystemConfiguration`	bool	Allow system configuration changes
`AllowedUserManagement`	bool	Allow user management operations
`AllowedLogManagement`	bool	Allow log management operations

Container deployment

Official images use CONFIG_PATH=/etc/project. Persist that directory so configuration, secrets, and projects survive image updates. The published image is coreflux/coreflux-mqtt-broker.

Docker
Docker Compose
Kubernetes

Same pattern as Installation: named volume at /etc/project, MQTT on 1883, WebSocket on 5000, ops on 9100.

docker run --pull=always -d --name coreflux_broker \
  -p 1883:1883 -p 5000:5000 -p 9100:9100 \
  -v project-volume:/etc/project \
  coreflux/coreflux-mqtt-broker:latest \
  --project https://github.com/org/my-iot-project.git --branch main

Import JSON on first boot by mounting files and passing --config / --users (add --config-force / --users-force only when you intend to replace existing state):

docker run --pull=always -d --name coreflux_broker \
  -p 1883:1883 -p 5000:5000 -p 9100:9100 \
  -v project-volume:/etc/project \
  -v /host/config:/config:ro \
  coreflux/coreflux-mqtt-broker:latest \
  --config /config/broker-config.json \
  --users /config/users.json

Probe liveness with curl http://localhost:9100/health. The image has no shell, so do not use exec healthchecks.

Use the Compose file from Installation. To load a project, add command on the broker service:

services:
  broker:
    image: coreflux/coreflux-mqtt-broker:latest
    ports:
      - "1883:1883"
      - "5000:5000"
      - "9100:9100"
    volumes:
      - broker-data:/etc/project
    command:
      - "--project"
      - "https://github.com/org/my-iot-project.git"
      - "--branch"
      - "main"
    restart: unless-stopped

volumes:
  broker-data:

The image already sets CONFIG_PATH=/etc/project. Override COREFLUX_DATA_PATH only if you change the mount path.

Mount a PVC at /etc/project. Use HTTP probes on port 9100 (the image has no shell).

apiVersion: apps/v1
kind: Deployment
metadata:
  name: coreflux-broker
spec:
  replicas: 1
  selector:
    matchLabels:
      app: coreflux-broker
  template:
    metadata:
      labels:
        app: coreflux-broker
    spec:
      containers:
        - name: broker
          image: coreflux/coreflux-mqtt-broker:latest
          args:
            - "--project"
            - "https://github.com/org/my-iot-project.git"
            - "--branch"
            - "production"
          ports:
            - containerPort: 1883
              name: mqtt
            - containerPort: 5000
              name: websocket
            - containerPort: 9100
              name: ops
          env:
            - name: CONFIG_PATH
              value: "/etc/project"
          volumeMounts:
            - name: data
              mountPath: /etc/project
          livenessProbe:
            httpGet:
              path: /health
              port: 9100
            initialDelaySeconds: 5
            periodSeconds: 15
          readinessProbe:
            httpGet:
              path: /ready
              port: 9100
            initialDelaySeconds: 5
            periodSeconds: 10
      volumes:
        - name: data
          persistentVolumeClaim:
            claimName: coreflux-data

Service installation

Prefer the install method from Installation. Use --install only for portable binaries.

Linux packages
Windows
Portable Linux

APT and DNF packages already register coreflux-broker.service, install under /opt/coreflux-broker, and set COREFLUX_DATA_PATH=/var/lib/coreflux.

sudo systemctl status coreflux-broker
sudo systemctl restart coreflux-broker
sudo journalctl -u coreflux-broker -f

To add startup flags (for example --project), override the unit:

sudo systemctl edit coreflux-broker

[Service]
ExecStart=
ExecStart=/opt/coreflux-broker/CorefluxMQTTBroker --project https://github.com/org/my-iot-project.git --branch main

Then sudo systemctl daemon-reload && sudo systemctl restart coreflux-broker.

Installation registers the service with sc create. For a portable zip, you can instead run as Administrator:

.\CorefluxMQTTBroker.exe --install
net start CorefluxMQTTBroker
Get-Service CorefluxMQTTBroker

To apply JSON once before the service owns the process, run the broker in the foreground with --config / --users, stop it, then install or start the service.

For a tarball (not APT/DNF), run as root:

sudo ./CorefluxMQTTBroker --install

That writes a systemd unit. For production, still prefer packages.coreflux.org so upgrades and COREFLUX_DATA_PATH stay consistent.

Best practices

Set the data path in the environment

Use COREFLUX_DATA_PATH or CONFIG_PATH so --config and --users land in the same directory the broker uses at runtime. Docker images already set CONFIG_PATH=/etc/project.

Use force flags only when you mean to reset

-cf and -uf overwrite existing configuration. Back up first.

Ship LoT as a project

Load Actions, Models, Routes, and Rules with --project, not with ad-hoc .lot file flags at process start.

Persist the data volume

Always mount a volume at /etc/project in Docker and Kubernetes. Without it, configuration, secrets, and projects disappear when the container is recreated.

Troubleshooting

Configuration not applied

Confirm COREFLUX_DATA_PATH / CONFIG_PATH matches the volume you mounted.
If files already exist in that directory, add --config-force / --users-force only if you intend to replace them.
Check logs for validation errors.

Port already in use

sudo lsof -i :1883

On Windows: netstat -ano | findstr :1883Stop the other listener or change the broker port in configuration.

Permission denied on Linux

The package service user is coreflux, with state under /var/lib/coreflux. The service user needs read access to certificates and write access to the data directory.

Quick Start

Coreflux MQTT Broker

LoT Language

Coreflux HUB

VS Code - LoT Notebooks

Using AI with Coreflux

Product Updates

Configure the broker before it starts

Command-line options

Configuration

Projects and licenses

Other options

Basic usage

Starting with configuration files

Force overwrite existing configuration

Loading a project at startup

Configuration files

Broker configuration (JSON)

Users configuration (JSON)

Container deployment

Service installation

Best practices

Troubleshooting

Next Steps

Broker Configuration

Environment Variables & Secrets

​Configure the broker before it starts

​Command-line options

​Configuration

​Projects and licenses

​Other options

​Basic usage

​Starting with configuration files

​Force overwrite existing configuration

​Loading a project at startup

​Configuration files

​Broker configuration (JSON)

​Users configuration (JSON)

​Container deployment

​Service installation

​Best practices

​Troubleshooting

​Next Steps

Broker Configuration

Environment Variables & Secrets

Configure the broker before it starts

Command-line options

Configuration

Projects and licenses

Other options

Basic usage

Starting with configuration files

Force overwrite existing configuration

Loading a project at startup

Configuration files

Broker configuration (JSON)

Users configuration (JSON)

Container deployment

Service installation

Best practices

Troubleshooting

Next Steps