> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreflux.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Startup Options & Deployment

> Configure broker startup with command-line options, deploy to containers, and install as a system service

## 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.

<Tip>
  **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.
</Tip>

***

## In This Page

| Section                                       | Description                         |
| --------------------------------------------- | ----------------------------------- |
| [Command-Line Options](#command-line-options) | All available startup flags         |
| [Configuration Files](#configuration-files)   | Broker, users, and LoT file formats |
| [Docker Deployment](#docker-deployment)       | Container and Kubernetes deployment |
| [Service Installation](#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

<Tabs>
  <Tab title="Linux/macOS">
    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Windows">
    ```powershell theme={null}
    # 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
    ```
  </Tab>
</Tabs>

### Force Overwrite Existing Configuration

By default, if configuration files already exist, startup arguments are ignored. Use force flags to overwrite:

```bash theme={null}
# 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
```

<Warning>
  Force flags overwrite existing configurations. Back up your current configuration before using them.
</Warning>

### Loading LoT Entities at Startup

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

```bash theme={null}
# 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
```

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

***

## Configuration Files

### Broker Configuration (JSON)

The broker configuration file defines MQTT service settings:

```json theme={null}
{
  "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:

```json theme={null}
[
  {
    "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:**

```lot theme={null}
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:**

```lot theme={null}
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:

<Tabs>
  <Tab title="Docker" icon="docker">
    Run the broker with mounted configuration files:

    ```bash theme={null}
    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
  </Tab>

  <Tab title="Docker Compose" icon="layer-group">
    Create a `docker-compose.yml` file:

    ```yaml theme={null}
    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`
  </Tab>

  <Tab title="Kubernetes" icon="dharmachakra">
    **Step 1: Create ConfigMap for configuration files**

    ```yaml theme={null}
    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**

    ```yaml theme={null}
    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`
  </Tab>
</Tabs>

***

## Service Installation

Install Coreflux as a system service for automatic startup:

<Tabs>
  <Tab title="Windows" icon="windows">
    <Steps>
      <Step title="Download the Broker">
        Download the Windows binary from [coreflux.org/downloads](https://www.coreflux.org/downloads).
      </Step>

      <Step title="Open Administrator Command Prompt">
        Right-click Command Prompt and select "Run as administrator".
      </Step>

      <Step title="Install the Service">
        Navigate to the broker directory and run:

        ```powershell theme={null}
        .\CorefluxMQTTBroker.exe --install
        ```

        <Check>
          Response: `Coreflux MQTT Broker service installed successfully`
        </Check>
      </Step>

      <Step title="Start the Service">
        Start the service using Windows Services or:

        ```powershell theme={null}
        net start CorefluxMQTTBroker
        ```
      </Step>

      <Step title="Verify Installation">
        Check the service is running:

        ```powershell theme={null}
        Get-Service CorefluxMQTTBroker
        ```
      </Step>
    </Steps>

    **Install with Pre-Configuration:**

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

    ```powershell theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Linux" icon="linux">
    <Steps>
      <Step title="Download and Extract">
        ```bash theme={null}
        # 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
        ```
      </Step>

      <Step title="Create a System User">
        ```bash theme={null}
        sudo useradd -r -s /bin/false coreflux
        sudo chown -R coreflux:coreflux /opt/coreflux
        ```
      </Step>

      <Step title="Create systemd Service File">
        Create `/etc/systemd/system/coreflux.service`:

        ```ini theme={null}
        [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
        ```
      </Step>

      <Step title="Enable and Start the Service">
        ```bash theme={null}
        sudo systemctl daemon-reload
        sudo systemctl enable coreflux
        sudo systemctl start coreflux
        ```

        <Check>
          Verify with: `sudo systemctl status coreflux`
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Raspberry Pi" icon="raspberry-pi">
    The Coreflux broker runs on ARM devices like Raspberry Pi:

    <Steps>
      <Step title="Download ARM Binary">
        ```bash theme={null}
        # 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
        ```
      </Step>

      <Step title="Create Configuration Directory">
        ```bash theme={null}
        sudo mkdir -p /opt/coreflux/config

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

        Add your configuration (see [Broker Configuration](#broker-configuration-json) above).
      </Step>

      <Step title="Create systemd Service">
        Create `/etc/systemd/system/coreflux.service`:

        ```ini theme={null}
        [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
        ```
      </Step>

      <Step title="Enable Auto-Start on Boot">
        ```bash theme={null}
        sudo systemctl daemon-reload
        sudo systemctl enable coreflux
        sudo systemctl start coreflux

        # Check status
        sudo systemctl status coreflux
        ```

        <Check>
          The broker will now start automatically when your Raspberry Pi boots.
        </Check>
      </Step>
    </Steps>

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

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use Force Flags Carefully" icon="warning">
    The `-cf` and `-uf` flags overwrite existing configurations. Only use them when you intentionally want to reset configurations. Back up existing configs first.
  </Accordion>

  <Accordion title="Secure Configuration Files" icon="lock">
    Users configuration contains passwords. Ensure proper file permissions:

    ```bash theme={null}
    chmod 600 /opt/coreflux/config/users.json
    ```

    In production, consider using secrets management (Kubernetes Secrets, HashiCorp Vault).
  </Accordion>

  <Accordion title="Use Persistent Volumes in Containers" icon="database">
    Always mount a persistent volume for `/app/Coreflux` in Docker/Kubernetes. This preserves your broker state across container restarts.
  </Accordion>

  <Accordion title="Validate Before Deployment" icon="check">
    Test your configuration files locally before deploying to production. Start the broker manually and verify it works correctly.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Configuration Not Applied">
    If your startup configuration is not being applied:

    1. Check if configuration files already exist in the data directory
    2. Use the force flags (`-cf`, `-uf`) to overwrite existing configuration
    3. Check logs for validation errors
  </Accordion>

  <Accordion title="Port Already in Use">
    If the broker fails to start due to port conflicts:

    ```bash theme={null}
    # 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.
  </Accordion>

  <Accordion title="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

    ```bash theme={null}
    sudo chown -R coreflux:coreflux /opt/coreflux
    ```
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Broker Configuration" icon="gear" href="/mqtt-broker/configuration">
    Detailed configuration options and TLS setup.
  </Card>

  <Card title="System Topics" icon="terminal" href="/mqtt-broker/sys-topics">
    Monitor and control your broker via \$SYS topics.
  </Card>
</CardGroup>