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

> Start the broker with CLI flags, projects, and packages — Docker, Linux systemd, and Windows services

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

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

For install commands (Docker, APT, DNF, Windows), start with [Installation](/latest/quick-start/installation). For `COREFLUX_*` variables, secrets, and `.env` files, see [Environment Variables & Secrets](/latest/mqtt-broker/secrets-and-env).

***

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

<Note>
  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.
</Note>

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

<Tabs>
  <Tab title="Linux">
    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    # 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 wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.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
    ```
  </Tab>
</Tabs>

### Force overwrite existing configuration

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

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# 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 a project at startup

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
# 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
```

<Check>
  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.
</Check>

***

## Configuration files

### Broker configuration (JSON)

The broker configuration file defines MQTT service settings:

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
{
  "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
}
```

<Note>
  For every supported field (ports, TLS/mTLS, sessions, performance, data paths, ops, durability), see [Broker Configuration](/latest/mqtt-broker/configuration).
</Note>

### Users configuration (JSON)

The users configuration file defines MQTT users and their permissions:

```json wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
[
  {
    "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`.

<Tabs>
  <Tab title="Docker" icon="docker">
    Same pattern as [Installation](/latest/quick-start/installation): named volume at `/etc/project`, MQTT on `1883`, WebSocket on `5000`, ops on `9100`.

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    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):

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    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.
  </Tab>

  <Tab title="Docker Compose" icon="layer-group">
    Use the Compose file from [Installation](/latest/quick-start/installation). To load a project, add `command` on the broker service:

    ```yaml wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    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.
  </Tab>

  <Tab title="Kubernetes" icon="dharmachakra">
    Mount a PVC at `/etc/project`. Use HTTP probes on port `9100` (the image has no shell).

    ```yaml wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    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
    ```
  </Tab>
</Tabs>

***

## Service installation

Prefer the install method from [Installation](/latest/quick-start/installation). Use `--install` only for portable binaries.

<Tabs>
  <Tab title="Linux packages" icon="linux">
    APT and DNF packages already register **`coreflux-broker.service`**, install under `/opt/coreflux-broker`, and set `COREFLUX_DATA_PATH=/var/lib/coreflux`.

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    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:

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    sudo systemctl edit coreflux-broker
    ```

    ```ini wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    [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`.
  </Tab>

  <Tab title="Windows" icon="windows">
    [Installation](/latest/quick-start/installation) registers the service with `sc create`. For a portable zip, you can instead run as Administrator:

    ```powershell wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    .\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.
  </Tab>

  <Tab title="Portable Linux" icon="terminal">
    For a tarball (not APT/DNF), run as root:

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    sudo ./CorefluxMQTTBroker --install
    ```

    That writes a systemd unit. For production, still prefer [packages.coreflux.org](https://packages.coreflux.org) so upgrades and `COREFLUX_DATA_PATH` stay consistent.
  </Tab>
</Tabs>

***

## Best practices

<AccordionGroup>
  <Accordion title="Set the data path in the environment" icon="folder">
    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`.
  </Accordion>

  <Accordion title="Use force flags only when you mean to reset" icon="warning">
    `-cf` and `-uf` overwrite existing configuration. Back up first.
  </Accordion>

  <Accordion title="Ship LoT as a project" icon="book">
    Load Actions, Models, Routes, and Rules with `--project`, not with ad-hoc `.lot` file flags at process start.
  </Accordion>

  <Accordion title="Persist the data volume" icon="database">
    Always mount a volume at `/etc/project` in Docker and Kubernetes. Without it, configuration, secrets, and projects disappear when the container is recreated.
  </Accordion>
</AccordionGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Configuration not applied">
    1. Confirm `COREFLUX_DATA_PATH` / `CONFIG_PATH` matches the volume you mounted.
    2. If files already exist in that directory, add `--config-force` / `--users-force` only if you intend to replace them.
    3. Check logs for validation errors.
  </Accordion>

  <Accordion title="Port already in use">
    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    sudo lsof -i :1883
    ```

    On Windows: `netstat -ano | findstr :1883`

    Stop the other listener or change the broker port in configuration.
  </Accordion>

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

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Broker Configuration" icon="gear" href="/latest/mqtt-broker/configuration">
    Ports, TLS, sessions, ops, and every JSON field.
  </Card>

  <Card title="Environment Variables & Secrets" icon="key" href="/latest/mqtt-broker/secrets-and-env">
    Data path, COREFLUX\_\* variables, .env, and encrypted secrets.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.