Startup Options & Deployment

Overview

The Coreflux MQTT Broker can be configured at startup through command-line arguments, making it ideal for automated deployments, containerized environments, and system service installations. Instead of manually configuring the broker after startup, you can pass configuration files directly—perfect for CI/CD pipelines, Docker, Kubernetes, and production provisioning.

Think of startup options as a recipe card for your broker. You tell it exactly how to configure itself before it starts—which users to create, which routes to load, which actions to deploy. The broker reads the recipe and sets itself up automatically.

In This Page

Section	Description
Command-Line Options	All available startup flags
Configuration Files	Broker, users, and LoT file formats
Docker Deployment	Container and Kubernetes deployment
Service Installation	Windows, Linux, and Raspberry Pi

Command-Line Options

Configuration Management

Option	Long Form	Description
`-c`	`--config`	Path to broker configuration JSON file
`-cf`	`--config-force`	Force overwrite existing broker configuration
`-u`	`--users`	Path to users configuration JSON file
`-uf`	`--users-force`	Force overwrite existing users configuration
`-p`	`--path`	Custom base path for Coreflux data directory

LoT Entity Loading

Option	Long Form	Description
`-lotrt`	`--lot-routes`	Path to Routes definition file
`-lota`	`--lot-actions`	Path to Actions definition file
`-lotm`	`--lot-models`	Path to Models definition file
`-lotrl`	`--lot-rules`	Path to Rules definition file

Other Options

Option	Long Form	Description
`-I`	`--install`	Install as a system service
`-h`	`--help`	Display help information

Environment Variables

Variable	Description	Default
`CONFIG_PATH`	Base directory for Coreflux configuration files	Application directory

Basic Usage

Starting with Configuration Files

Linux/macOS
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 files already exist, startup arguments are 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 LoT Entities at Startup

Pre-load Actions, Models, Routes, and Rules when the broker starts:

# Load all LoT entities
./CorefluxMQTTBroker \
    --config /path/to/broker-config.json \
    --users /path/to/users.json \
    --lot-routes /path/to/routes.lot \
    --lot-actions /path/to/actions.lot \
    --lot-models /path/to/models.lot \
    --lot-rules /path/to/rules.lot

This is ideal for deploying complete IoT solutions. Package your broker, users, and all LoT logic into a single startup command.

Configuration Files

Broker Configuration (JSON)

The broker configuration file defines MQTT service settings:

{
  "Name": "MyCorefluxBroker",
  "Port": 1883,
  "TlsPort": 8883,
  "WebsocketPort": 5000,
  "WebsocketPortTls": 443,
  "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
}

Broker Configuration Properties

Property	Type	Default	Description
`Name`	string	-	Name of the MQTT broker
`Port`	int	1883	Default MQTT port
`TlsPort`	int	8883	TLS-encrypted MQTT port
`WebsocketPort`	int	5000	MQTT over WebSocket port
`WebsocketPortTls`	int	443	MQTT over WebSocket with TLS port
`BindIPForMQTT`	string	0.0.0.0	IP address to bind for MQTT
`AnonymousLogin`	bool	false	Allow anonymous connections
`FullDebugLog`	bool	false	Enable detailed debug logging

Users Configuration (JSON)

The users configuration file defines MQTT users and their permissions:

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

User Permission Properties

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
`AllowedAssetManipulation`	bool	Allow LoT entity installation/removal
`AllowedUserManagement`	bool	Allow user management operations
`AllowedLogManagement`	bool	Allow log management operations

LoT Entity Files

Create .lot files with your entity definitions: actions.lot:

DEFINE ACTION Heartbeat
ON EVERY 10 SECONDS DO
    PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"

DEFINE ACTION TemperatureProcessor
ON TOPIC "sensors/+/temperature" DO
    SET "sensor_id" WITH TOPIC POSITION 2
    PUBLISH TOPIC "processed/" + {sensor_id} WITH PAYLOAD

routes.lot:

DEFINE ROUTE DatabaseRoute WITH TYPE POSTGRESQL
    ADD POSTGRESQL_CONFIG
        WITH HOST "localhost"
        WITH PORT 5432
        WITH DATABASE "iot_data"
        WITH USERNAME "postgres"
        WITH PASSWORD "password"
    ADD MAPPING "StoreSensorData"
        WITH SOURCE_TOPIC "sensors/+/data"
        WITH QUERY "INSERT INTO readings (topic, value) VALUES ('{source_topic}', '{payload}')"

Container Deployment

Deploy the Coreflux broker using containers or orchestration platforms:

Docker
Docker Compose
Kubernetes

Run the broker with mounted configuration files:

docker run -d \
  --name coreflux-broker \
  -p 1883:1883 \
  -p 5000:5000 \
  -v /host/config:/config:ro \
  -v /host/data:/app/Coreflux \
  coreflux/broker:latest \
  --config /config/broker-config.json \
  --users /config/users.json \
  --lot-routes /config/routes.lot \
  --lot-actions /config/actions.lot \
  --config-force \
  --users-force

Key volume mounts:

/config — Read-only mount for configuration files
/app/Coreflux — Persistent storage for broker data

Create a docker-compose.yml file:

version: '3.8'

services:
  coreflux-broker:
    image: coreflux/broker:latest
    container_name: coreflux-broker
    ports:
      - "1883:1883"
      - "8883:8883"
      - "5000:5000"
    volumes:
      - ./config:/config:ro
      - broker-data:/app/Coreflux
    command: >
      --config /config/broker-config.json
      --users /config/users.json
      --lot-routes /config/routes.lot
      --lot-actions /config/actions.lot
      --config-force
      --users-force
    environment:
      - CONFIG_PATH=/app/Coreflux
    restart: unless-stopped

volumes:
  broker-data:

Start with: docker-compose up -d

Step 1: Create ConfigMap for configuration files

apiVersion: v1
kind: ConfigMap
metadata:
  name: coreflux-config
data:
  broker-config.json: |
    {
      "Name": "KubernetesBroker",
      "Port": 1883,
      "AnonymousLogin": false
    }
  users.json: |
    [
      {
        "UserName": "root",
        "Password": "secure-password",
        "AllowedBaseTopic": "#",
        "AllowedSystemConfiguration": true,
        "AllowedAssetManipulation": true,
        "AllowedUserManagement": true,
        "AllowedLogManagement": true
      }
    ]
  actions.lot: |
    DEFINE ACTION Heartbeat
    ON EVERY 10 SECONDS DO
        PUBLISH TOPIC "system/heartbeat" WITH TIMESTAMP "UTC"

Step 2: Create Deployment and Service

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/broker:latest
        ports:
        - containerPort: 1883
        - containerPort: 5000
        args:
        - "--config"
        - "/config/broker-config.json"
        - "--users"
        - "/config/users.json"
        - "--lot-actions"
        - "/config/actions.lot"
        - "--config-force"
        - "--users-force"
        volumeMounts:
        - name: config
          mountPath: /config
        - name: data
          mountPath: /app/Coreflux
      volumes:
      - name: config
        configMap:
          name: coreflux-config
      - name: data
        persistentVolumeClaim:
          claimName: coreflux-data
---
apiVersion: v1
kind: Service
metadata:
  name: coreflux-broker
spec:
  selector:
    app: coreflux-broker
  ports:
  - name: mqtt
    port: 1883
    targetPort: 1883
  - name: websocket
    port: 5000
    targetPort: 5000
  type: LoadBalancer

Apply with: kubectl apply -f coreflux-deployment.yaml

Service Installation

Install Coreflux as a system service for automatic startup:

Windows
Linux
Raspberry Pi

Download the Broker

Download the Windows binary from coreflux.org/downloads.

Open Administrator Command Prompt

Right-click Command Prompt and select “Run as administrator”.

Install the Service

Navigate to the broker directory and run:

.\CorefluxMQTTBroker.exe --install

Response: Coreflux MQTT Broker service installed successfully

Start the Service

Start the service using Windows Services or:

net start CorefluxMQTTBroker

Verify Installation

Check the service is running:

Get-Service CorefluxMQTTBroker

Install with Pre-Configuration:To install with pre-configured settings, first run the broker once with your configuration:

# Configure the broker first
.\CorefluxMQTTBroker.exe `
    --config C:\Coreflux\config\broker-config.json `
    --users C:\Coreflux\config\users.json `
    --config-force --users-force

# Stop the broker (Ctrl+C), then install as service
.\CorefluxMQTTBroker.exe --install

Download and Extract

# Download the Linux binary
wget https://coreflux.org/downloads/coreflux-broker-linux-x64.tar.gz

# Extract to /opt
sudo tar -xzf coreflux-broker-linux-x64.tar.gz -C /opt/
sudo mv /opt/coreflux-broker /opt/coreflux

# Make executable
sudo chmod +x /opt/coreflux/CorefluxMQTTBroker

Create a System User

sudo useradd -r -s /bin/false coreflux
sudo chown -R coreflux:coreflux /opt/coreflux

Create systemd Service File

Create /etc/systemd/system/coreflux.service:

[Unit]
Description=Coreflux MQTT Broker
After=network.target

[Service]
Type=simple
User=coreflux
Group=coreflux
WorkingDirectory=/opt/coreflux
ExecStart=/opt/coreflux/CorefluxMQTTBroker \
    --config /opt/coreflux/config/broker-config.json \
    --users /opt/coreflux/config/users.json
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable and Start the Service

sudo systemctl daemon-reload
sudo systemctl enable coreflux
sudo systemctl start coreflux

Verify with: sudo systemctl status coreflux

The Coreflux broker runs on ARM devices like Raspberry Pi:

Download ARM Binary

# For Raspberry Pi 4 (64-bit OS)
wget https://coreflux.org/downloads/coreflux-broker-linux-arm64.tar.gz

# For Raspberry Pi 3/Zero (32-bit OS)
wget https://coreflux.org/downloads/coreflux-broker-linux-arm.tar.gz

# Extract
sudo tar -xzf coreflux-broker-linux-arm64.tar.gz -C /opt/
sudo chmod +x /opt/coreflux/CorefluxMQTTBroker

Create Configuration Directory

sudo mkdir -p /opt/coreflux/config

# Create broker config
sudo nano /opt/coreflux/config/broker-config.json

Add your configuration (see Broker Configuration above).

Create systemd Service

Create /etc/systemd/system/coreflux.service:

[Unit]
Description=Coreflux MQTT Broker
After=network.target

[Service]
Type=simple
User=pi
WorkingDirectory=/opt/coreflux
ExecStart=/opt/coreflux/CorefluxMQTTBroker \
    --config /opt/coreflux/config/broker-config.json \
    --users /opt/coreflux/config/users.json
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target

Enable Auto-Start on Boot

sudo systemctl daemon-reload
sudo systemctl enable coreflux
sudo systemctl start coreflux

# Check status
sudo systemctl status coreflux

The broker will now start automatically when your Raspberry Pi boots.

For headless Raspberry Pi deployments, pre-configure the broker on a development machine, then copy the entire /opt/coreflux directory to your Pi.

File Storage Locations

When the broker runs, it stores data in these locations:

File	Path	Description
Broker Config	`{base}/Coreflux/bin/Anselmo.ralph`	Encrypted broker configuration
Users Config	`{base}/Coreflux/bin/ana.malhoa`	Encrypted users configuration
Routes	`{base}/Coreflux/bin/Roberto.Leal`	Routes definitions
Actions	`{base}/Coreflux/bin/Saul.Ricardo`	Actions definitions
Models	`{base}/Coreflux/bin/Marco.Paulo`	Models definitions
Rules	`{base}/Coreflux/bin/Ze.Cabra`	Permission rules
Python Scripts	`{base}/Coreflux/bin/Python.Scripts`	Python script definitions
Logs	`{base}/Coreflux/log/`	Log files

Where {base} is determined by:

The CONFIG_PATH environment variable, or
The --path argument, or
The application’s base directory

Best Practices

Use Force Flags Carefully

The -cf and -uf flags overwrite existing configurations. Only use them when you intentionally want to reset configurations. Back up existing configs first.

Secure Configuration Files

Users configuration contains passwords. Ensure proper file permissions:

chmod 600 /opt/coreflux/config/users.json

In production, consider using secrets management (Kubernetes Secrets, HashiCorp Vault).

Use Persistent Volumes in Containers

Always mount a persistent volume for /app/Coreflux in Docker/Kubernetes. This preserves your broker state across container restarts.

Validate Before Deployment

Test your configuration files locally before deploying to production. Start the broker manually and verify it works correctly.

Troubleshooting

Configuration Not Applied

If your startup configuration is not being applied:

Check if configuration files already exist in the data directory
Use the force flags (-cf, -uf) to overwrite existing configuration
Check logs for validation errors

Port Already in Use

If the broker fails to start due to port conflicts:

# Check what's using port 1883
sudo lsof -i :1883

# Or on Windows
netstat -ano | findstr :1883

Either stop the conflicting service or change the broker port in your configuration.

Permission Denied on Linux

Ensure the service user has:

Read access to configuration files
Write access to the data directory
Proper permissions for TLS certificate files

sudo chown -R coreflux:coreflux /opt/coreflux

Next Steps

Broker Configuration

Detailed configuration options and TLS setup.

System Topics

Monitor and control your broker via $SYS topics.

Quick Start

MQTT Broker

LoT Language

LoT Notebooks

Actions

Routes

Models

Rules

Overview

In This Page

Command-Line Options

Configuration Management

LoT Entity Loading

Other Options

Environment Variables

Basic Usage

Starting with Configuration Files

Force Overwrite Existing Configuration

Loading LoT Entities at Startup

Configuration Files

Broker Configuration (JSON)

Broker Configuration Properties

Users Configuration (JSON)

User Permission Properties

LoT Entity Files

Container Deployment

Service Installation

File Storage Locations

Best Practices

Troubleshooting

Next Steps

Broker Configuration

System Topics

Quick Start

MQTT Broker

LoT Language

LoT Notebooks

Actions

Routes

Models

Rules

​Overview

​In This Page

​Command-Line Options

​Configuration Management

​LoT Entity Loading

​Other Options

​Environment Variables

​Basic Usage

​Starting with Configuration Files

​Force Overwrite Existing Configuration

​Loading LoT Entities at Startup

​Configuration Files

​Broker Configuration (JSON)

​Broker Configuration Properties

​Users Configuration (JSON)

​User Permission Properties

​LoT Entity Files

​Container Deployment

​Service Installation

​File Storage Locations

​Best Practices

​Troubleshooting

​Next Steps

Broker Configuration

System Topics

Overview

In This Page

Command-Line Options

Configuration Management

LoT Entity Loading

Other Options

Environment Variables

Basic Usage

Starting with Configuration Files

Force Overwrite Existing Configuration

Loading LoT Entities at Startup

Configuration Files

Broker Configuration (JSON)

Broker Configuration Properties

Users Configuration (JSON)

User Permission Properties

LoT Entity Files

Container Deployment

Service Installation

File Storage Locations

Best Practices

Troubleshooting

Next Steps