> ## 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. For install commands (Docker, APT, DNF, Windows), start with [Installation](/v2.14/quick-start/installation). For `COREFLUX_*` variables, secrets, and `.env` files, see [Environment Variables & Secrets](/v2.14/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. ### 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** ```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 ``` **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 ``` ### 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. ### 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 ``` > [!TIP] > > 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: ```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](/v2.14/mqtt-broker/configuration). ### 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`. **Docker** Same pattern as [Installation](/v2.14/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. **Docker Compose** Use the Compose file from [Installation](/v2.14/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. **Kubernetes** 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 ``` *** ## Service installation Prefer the install method from [Installation](/v2.14/quick-start/installation). Use `--install` only for portable binaries. **Linux packages** 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`. **Windows** [Installation](/v2.14/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. **Portable Linux** 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. *** ## 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 writable volume at `/etc/project` in Docker and Kubernetes. Without it, configuration, secrets, projects, and the client-certificate trust store (`/etc/project/certs`) disappear when the container is recreated. The image runs as UID/GID `10001`; in Kubernetes set `fsGroup: 10001` if the volume is not already writable by that user. *** ## Troubleshooting > **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. > **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. > **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. *** ## Next Steps > **[Broker Configuration](/v2.14/mqtt-broker/configuration)** > > Ports, TLS, sessions, ops, and every JSON field. > **[Environment Variables & Secrets](/v2.14/mqtt-broker/secrets-and-env)** > > Data path, COREFLUX\_\* variables, .env, and encrypted secrets. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.