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

# Installation

> Get a Coreflux broker and HUB running in minutes with Docker, the HUB desktop app, a free Cloud Trial, or native installs for Windows and Linux.

## Install Coreflux

Most people should use **Docker** or **Docker Compose** for the broker and the [Coreflux HUB](/hub/overview). Just evaluating with nothing to install? Use the **Cloud Trial** tab. The **HUB desktop** tab is the standalone app. Native broker binaries and cloud droplets are in the remaining tabs.

> [!TIP]
>
> **Coreflux runs as a single install.** No separate databases or message queues—pick a method below and run it.

> **Default login credentials**
>
> Every local install method uses the same defaults:
>
> | Setting | Value |
> | - | - |
> | Username | `root` |
> | Password | `coreflux` |
>
> For a **Cloud Trial**, use the credentials from your email instead.

***

**Docker**

> [!TIP]
>
> **\~2 min** if Docker is already installed — broker, HUB, or both.

The broker and [Coreflux HUB](/hub/overview) are **separate images**. Pick the command that matches what you want to run. The HUB desktop app is in the **HUB desktop** tab.

> [!NOTE]
>
> New to Docker? Install it from the [official Docker install page](https://docs.docker.com/get-started/get-docker/), then confirm with `docker --version` before you continue. Images are on [Docker Hub](https://hub.docker.com/r/coreflux/coreflux-mqtt-broker).

**Broker only**

Start the broker. Docker fetches the latest image automatically:

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

MQTT is on `localhost:1883`. There is no HUB in this command — use **HUB only** or **Broker + HUB**, or the standalone HUB app.

**HUB only**

Start the HUB and connect it to a broker that is already running:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
docker run --pull=always -d --name coreflux_hub -p 3000:3000 -v hub-data:/opt/coreflux-hub/data coreflux/coreflux-hub:latest
```

Open `http://localhost:3000`. Click **New Connection** (or **Enter** on a saved one). If the broker is on the same machine, set **Protocol** `mqtt://`, **Host** `host.docker.internal` (Docker Desktop) or the host's LAN IP, and **Port** `1883` — not `localhost`, because the HUB proxies MQTT from inside its container.

**Broker + HUB**

Create a shared network and start both containers in one command:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
docker network create coreflux && docker run --pull=always -d --name coreflux_broker --network coreflux --network-alias broker -p 1883:1883 -p 5000:5000 -p 9100:9100 -v project-volume:/etc/project coreflux/coreflux-mqtt-broker:latest && docker run --pull=always -d --name coreflux_hub --network coreflux -p 3000:3000 -v hub-data:/opt/coreflux-hub/data coreflux/coreflux-hub:latest
```

Open the HUB at `http://localhost:3000`, click **New Connection**, and connect with **Protocol** `mqtt://`, **Host** `broker`, **Port** `1883` (or **Protocol** `ws://`, **Host** `broker`, **Port** `5000`, **Path** `mqtt`). Skip `docker network create coreflux &&` if the `coreflux` network already exists.

| Port | Service | Description |
| - | - | - |
| `1883` | Broker | MQTT (unencrypted) |
| `5000` | Broker | WebSocket / HTTP API |
| `9100` | Broker | `/health`, `/ready`, `/info`, `/metrics` |
| `3000` | HUB | [Coreflux HUB](/hub/overview) |

> [!WARNING]
>
> Port `3000` serves the HUB over plain HTTP. Open it on `localhost`, or put it behind a reverse proxy that terminates TLS and open it over HTTPS. Browsers only allow clipboard access on HTTPS or `localhost`, so on current HUB versions the copy buttons fail when you open the HUB as `http://<LAN IP>:3000`. See [Copy buttons don't work](#copy-buttons-dont-work-in-the-hub) under troubleshooting.

| Command | Broker fields on **New Connection** |
| - | - |
| Broker + HUB | Protocol `mqtt://`, Host `broker`, Port `1883` (or `ws://`, Host `broker`, Port `5000`, Path `mqtt`) |
| HUB only | Protocol `mqtt://`, Host `host.docker.internal` if the broker is on the same machine, or the broker's host address |

The HUB proxies MQTT from inside Docker, so **Host** `localhost` does not reach a broker container.

That's it—Coreflux is now running locally. Confirm it works under [Verify Installation](#verify-installation) below.

> **What does the broker command do?**
>
> Breaking the broker `docker run` down piece by piece:
>
> * `--pull=always` — always fetch the latest image before starting, so you never run a stale version.
> * `-d` — runs the container **detached** (in the background), so your terminal stays free.
> * `--name coreflux_broker` — names the container so you can reference it later (for example `docker logs coreflux_broker`).
> * `-p 1883:1883 -p 5000:5000 -p 9100:9100` — each `-p host:container` maps a port on your machine to the same port inside the container. See the port table above for what each one is for.
> * `-v project-volume:/etc/project` — mounts a named volume so your project (LoT, routes, configuration) persists across restarts and image updates.
> * `coreflux/coreflux-mqtt-broker:latest` — the broker image, pulled from Docker Hub. The HUB image is `coreflux/coreflux-hub:latest`.

> **TLS/SSL Ports (when using certificates)**
>
> If you configure TLS certificates, expose these additional broker ports (`8883` and `5443`):
>
> ```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 -p 8883:8883 -p 5443:5443 -v project-volume:/etc/project coreflux/coreflux-mqtt-broker:latest
> ```
>
> | Port | Protocol | Description |
> | - | - | - |
> | `8883` | TCP/TLS | MQTT over TLS |
> | `5443` | WSS | WebSocket / HTTP API over TLS |
>
> See [Broker Configuration](/v2.14/mqtt-broker/configuration) for TLS setup.

**Docker Compose**

> [!TIP]
>
> **\~3 min** if Docker is already installed — broker and HUB on one network.

Docker Compose starts the broker and the [Coreflux HUB](/hub/overview) as two services on a shared network. Use the `full` profile to run both, or start either service alone. The HUB desktop app is in the **HUB desktop** tab.

Create a directory, then add `docker-compose.yml`:

```yaml wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    # Coreflux — Broker + Hub deployment
    #
    # Profiles:
    #   full   -> broker + hub, on the same network
    #   broker -> broker only
    #   hub    -> hub only
    #
    # Usage:
    #   docker compose --profile full up    # broker + hub
    #   docker compose --profile broker up  # broker only
    #   docker compose --profile hub up     # hub only

    services:
      broker:
        image: coreflux/coreflux-mqtt-broker:latest
        profiles: [full, broker]
        container_name: coreflux-broker
        restart: unless-stopped
        ports:
          - "1883:1883"   # MQTT (plain TCP)
          - "8883:8883"   # MQTT over TLS
          - "5000:5000"   # WebSocket transport / HTTP API
          - "5443:5443"   # WebSocket / HTTP API over TLS
          - "9100:9100"   # Operational endpoints: /health /ready /info /metrics
        volumes:
          # Persists everything under /etc/project/Coreflux (encrypted config,
          # routes, actions, models, rules, logs, stats, projects).
          - broker-data:/etc/project
        # The published image has no shell, so a shell-based
        # healthcheck cannot run inside the container. Check health externally
        # via HTTP GET http://localhost:9100/health.
        healthcheck:
          disable: true

      hub:
        image: coreflux/coreflux-hub:latest
        profiles: [full, hub]
        container_name: coreflux-hub
        restart: unless-stopped
        ports:
          - "3000:3000"   # Web UI + API + MQTT WebSocket proxy (plain HTTP)
        volumes:
          # Persists writable Hub state (e.g. theme-media uploads).
          - hub-data:/opt/coreflux-hub/data
        # environment:
        #   - GROQ_API_KEY=...   # optional, only for the Hub AI assistant feature
        #
        # NOTE: the Hub has no broker-connection env var. You choose the broker
        # from the Hub UI. Because the Hub proxies the MQTT connection
        # server-side, enter the broker's service name (not "localhost"):
        #   mqtt://broker:1883      (plain MQTT)
        #   ws://broker:5000/mqtt   (MQTT over WebSocket)

    volumes:
      broker-data:
      hub-data:

    # Both services attach to this network and resolve each other by service
    # name ("broker", "hub").
    networks:
      default:
        name: coreflux
```

Then start the stack:

**Broker + HUB**

From the directory that contains `docker-compose.yml`:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
docker compose --profile full up -d
```

Open the HUB at `http://localhost:3000`. Click **New Connection** and set **Protocol** `mqtt://`, **Host** `broker`, **Port** `1883` — the HUB proxies MQTT from inside Docker, so **Host** `localhost` does not reach the broker container.

**Broker only**

Start just the broker:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
docker compose --profile broker up -d
```

MQTT is on `localhost:1883`. There is no HUB in this profile.

**HUB only**

Start just the HUB (the broker must already be reachable on the `coreflux` network, or you will connect to a remote broker from the UI):

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
docker compose --profile hub up -d
```

Open the HUB at `http://localhost:3000`, click **New Connection**, and enter the broker **Host**, **Protocol**, and **Port** on the login screen.

| Command | Starts |
| - | - |
| `docker compose --profile full up` | broker + HUB |
| `docker compose --profile broker up` | broker only |
| `docker compose --profile hub up` | HUB only |

| Port | Service | Description |
| - | - | - |
| `1883` | Broker | MQTT (unencrypted) |
| `8883` | Broker | MQTT over TLS |
| `5000` | Broker | WebSocket / HTTP API |
| `5443` | Broker | WebSocket / HTTP API over TLS |
| `9100` | Broker | `/health`, `/ready`, `/info`, `/metrics` |
| `3000` | HUB | [Coreflux HUB](/hub/overview) |

> [!WARNING]
>
> Port `3000` serves the HUB over plain HTTP. Open it on `localhost`, or put it behind a reverse proxy that terminates TLS and open it over HTTPS. Browsers only allow clipboard access on HTTPS or `localhost`, so on current HUB versions the copy buttons fail when you open the HUB as `http://<LAN IP>:3000`. See [Copy buttons don't work](#copy-buttons-dont-work-in-the-hub) under troubleshooting.

> [!TIP]
>
> The HUB talks to the broker **from inside Docker**. On **New Connection**, set **Host** to the Compose service name (`broker`) — Protocol `mqtt://` and Port `1883`, or Protocol `ws://`, Port `5000`, and Path `mqtt`. Do not use **Host** `localhost`.

That's it—Coreflux is running locally. Confirm it works under [Verify Installation](#verify-installation) below.

> **Check broker health**
>
> The broker image has no shell, so Compose cannot run a healthcheck inside the container. Probe it from the host:
>
> ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> curl http://localhost:9100/health
> ```

> **Named volumes**
>
> `broker-data` persists broker configuration, routes, actions, models, rules, logs, and projects under `/etc/project`. `hub-data` persists HUB state such as theme-media uploads. Stopping or recreating containers does **not** delete these volumes.

> **Stop or remove the stack**
>
> ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> docker compose down
> ```
>
> Add `-v` only if you also want to delete the named volumes (this wipes broker and HUB data).

**HUB desktop**

> [!TIP]
>
> **\~2 min** — no Docker required for the HUB.

The standalone HUB is a desktop application for **Windows x64**, **Linux x64**, and **Linux ARM64**. It does not require a broker on the same machine.

**1. Download**

Download the HUB executable for your platform from [coreflux.org > Start Free](https://www.coreflux.org).

**2. Run**

Run the executable — the HUB window opens immediately.

**3. Connect**

Click **New Connection**. If the broker is on this machine, set **Protocol** `mqtt://`, **Host** `localhost`, **Port** `1883`, then enter the [default credentials](#default-login-credentials) and click **Connect**.

**Cloud Trial**

> [!TIP]
>
> **\~5 min**, nothing to install — hosted broker and HUB in your browser.

Get a hosted Coreflux instance without installing anything. Request a trial on the [Coreflux website](https://www.coreflux.org/), and you will receive an email with a **URL** (used for both the [Coreflux HUB](/hub/overview) and the MQTT broker) and **login credentials**.

**1. Request a trial**

Go to [coreflux.org](https://www.coreflux.org/) and submit a trial request using the form on the site.

**2. Check your email**

When your environment is ready, Coreflux sends an email with:

| Item | What you use it for |
| - | - |
| **URL** | Open the HUB in your browser and connect MQTT clients to the **same host** (broker and HUB share one address) |
| **Credentials** | Username and password for the HUB login screen and for MQTT clients |

> [!NOTE]
>
> The broker may take **up to 60 seconds** to be fully available after you receive the email. If the HUB or MQTT connection fails immediately, wait briefly and try again.

**3. Open the HUB**

Paste the URL from the email into your browser. Click **New Connection** (or **Enter** on a saved connection), enter your username and password, and click **Connect**. Use the broker host from the email if it is pre-filled differently than your trial URL.

![Coreflux HUB New Connection form with Local Hub, ws:// localhost port 5000 path mqtt, username root, and Connect](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/connections/hub-login-setup.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=63c5584209052080345ce3fdc8159511)

From the HUB you can deploy LoT Actions, browse MQTT topics in the Data Viewer, and manage Routes—same experience as a local Docker install.

**4. Connect MQTT clients**

Use the **same host** as the URL in your email (not `localhost`). For MQTT Explorer and other desktop clients:

| Setting | Value |
| - | - |
| Protocol | **MQTTS** (MQTT over TLS) |
| Port | **8883** |
| Username / Password | From your trial email |

In **MQTT Explorer** specifically: enable **Encryption**, and **disable Validate certificate** (the trial broker uses a certificate that desktop tools may not trust by default).

That's it—your trial is live and ready to use, with the broker and HUB already running on the URL from your email.

> [!WARNING]
>
> **HUB remote access:** If your browser blocks the HUB page, allow **unsecure access** (or proceed past the certificate warning) for the trial URL. Managed trial environments often use certificates that browsers flag on first visit.

> [!TIP]
>
> After the HUB loads, continue with [Getting Started](/v2.14/quick-start/getting-started) using the **Coreflux HUB** tabs—your trial already includes the HUB and broker.

**DigitalOcean**

> [!TIP]
>
> **\~10 min** (plus a DigitalOcean account) — production-ready broker running in the cloud.

Deploy Coreflux in seconds with our **1-Click Droplet** on DigitalOcean Marketplace. This is the fastest way to get a production-ready broker running in the cloud.

[![Deploy to DigitalOcean](https://mintcdn.com/coreflux/A0D_IE52Pl2ItO0u/do/buttons/do-btn-blue.svg?fit=max\&auto=format\&n=A0D_IE52Pl2ItO0u\&q=85\&s=f267478fefd55a7e41d52153947a2d65)](https://marketplace.digitalocean.com/apps/coreflux-mqtt-broker?refcode=b993040d0243\&action=deploy)

**1. Click Deploy**

Click the button above or visit the [Coreflux Marketplace page](https://marketplace.digitalocean.com/apps/coreflux-mqtt-broker?refcode=b993040d0243\&action=deploy).

**2. Choose Your Droplet Size**

Select a plan based on your needs:

| Plan | RAM | vCPUs | Best For |
| - | - | - | - |
| Basic | 1 GB | 1 | Development, testing |
| Basic | 2 GB | 1 | Small deployments |
| **Basic** | **4 GB** | **2** | **Recommended** ✓ |

> [!TIP]
>
> We recommend the **4 GB / 2 vCPU** droplet for most use cases. It provides headroom for LoT Actions, multiple routes, and moderate message throughput.

**3. Select Region**

Choose a datacenter close to your devices for lower latency.

**4. Create Droplet**

Click **Create Droplet** and wait \~60 seconds for deployment.

**5. Connect to Your Broker**

Once the droplet is ready, use the public IP address to connect:

| Setting | Value |
| - | - |
| Host | `<your-droplet-ip>` |
| Port | `1883` |
| Username | `root` |
| Password | `coreflux` |

That's it—your droplet is now running Coreflux and ready to use.

> [!WARNING]
>
> Change the default password immediately after first login. SSH into your droplet and update the broker configuration.

> **Exposed Ports**
>
> The Coreflux droplet exposes the following ports by default:
>
> | Port | Protocol | Description |
> | - | - | - |
> | `1883` | TCP | MQTT (unencrypted) |
> | `8883` | TCP/TLS | MQTT over TLS |
> | `5000` | WebSocket | WebSocket connections |
> | `443` | WSS | WebSocket over TLS |
>
> Configure your DigitalOcean firewall to restrict access as needed.

> **SSH Access**
>
> To manage your Coreflux installation via SSH:
>
> ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> ssh root@<your-droplet-ip>
> ```
>
> The Coreflux broker runs as a systemd service. Common commands:
>
> ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> # Check status
> sudo systemctl status coreflux
>
> # Restart broker
> sudo systemctl restart coreflux
>
> # View logs
> sudo journalctl -u coreflux -f
> ```

**Windows**

> [!TIP]
>
> **\~10 min** — broker running as a Windows service.

Download and install Coreflux, then register it as a Windows service using the native `sc` tool.

1. Download the Windows zip from [coreflux.org > Start Free](https://www.coreflux.org)
2. Extract the zip file to your preferred location (e.g., `C:\Coreflux`)
3. Open Command Prompt **as Administrator** and run:

```cmd wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
sc create CorefluxBroker binPath= "C:\Coreflux\CorefluxMQTTBroker.exe" start= auto DisplayName= "Coreflux MQTT Broker"
sc description CorefluxBroker "Coreflux MQTT Broker Service"
sc start CorefluxBroker
```

That's it—the service is now registered, set to start automatically on boot, and running, so Coreflux is ready to use. For the HUB, use the **HUB desktop** tab or run the HUB container from the **Docker** tab.

> **Manage the service**
>
> Use these native Windows commands to control the service:
>
> ```cmd wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> sc stop CorefluxBroker
> sc start CorefluxBroker
> sc query CorefluxBroker
> ```
>
> You can also manage it from **Services** (`services.msc`) in Windows.

> **Uninstall the service**
>
> Stop and remove the service with:
>
> ```cmd wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> sc stop CorefluxBroker
> sc delete CorefluxBroker
> ```

**Linux**

> [!TIP]
>
> **\~10 min** — broker installed from native packages and running as a systemd service.

Install the MQTT broker with your distribution's package manager. Packages are published at [packages.coreflux.org](https://packages.coreflux.org) for Debian-based systems (APT) and RHEL-compatible systems (DNF).

**Debian & Ubuntu (APT)**

APT is the package manager on Debian, Ubuntu, and Debian-based distributions—including **Raspberry Pi OS**. The package manager picks the right architecture (x64 or ARM64) for your machine.

| OS | Codename |
| - | - |
| Ubuntu 22.04 | `jammy` |
| Ubuntu 24.04 | `noble` |
| Debian 12 | `bookworm` |
| Debian 13 | `trixie` |

On Raspberry Pi OS, use the codename that matches your release (for example **bookworm** on Pi OS based on Debian 12, **noble** on releases based on Ubuntu 24.04).

**1. Check your distribution codename**

Run `lsb_release -a` and note the **Codename** line—you will use it in the next step.

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

Example output on Ubuntu 24.04:

```text wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
Codename:       noble
```

**2. Install the signing key**

Download Coreflux's archive signing key into `/usr/share/keyrings`:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
sudo mkdir -p /usr/share/keyrings

curl -fsSL https://packages.coreflux.org/keys/coreflux-archive-keyring.gpg \
  | sudo tee /usr/share/keyrings/coreflux-archive-keyring.gpg >/dev/null

sudo chmod 0644 /usr/share/keyrings/coreflux-archive-keyring.gpg
```

**3. Add the APT source**

Run **only** the command that matches your codename. Each command writes `/etc/apt/sources.list.d/coreflux.list`.

**Ubuntu 22.04 (jammy)**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/ubuntu jammy main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list
```

**Ubuntu 24.04 (noble)**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/ubuntu noble main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list
```

**Debian 12 (bookworm)**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/debian bookworm main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list
```

**Debian 13 (trixie)**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
echo "deb [signed-by=/usr/share/keyrings/coreflux-archive-keyring.gpg] https://packages.coreflux.org/deb/debian trixie main" \
  | sudo tee /etc/apt/sources.list.d/coreflux.list
```

**4. Install coreflux-broker**

Refresh package lists and install the broker package:

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

Optional — list available versions before installing:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
apt-cache policy coreflux-broker
```

**5. Confirm the service is running**

The package registers and starts `coreflux-broker` as a systemd service:

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

> [!TIP]
>
> **active (running)** means Coreflux is up. MQTT listens on port `1883` by default.

That's it—the broker is installed under `/opt/coreflux-broker` and managed by systemd. Confirm it works under [Verify Installation](#verify-installation) below. For the HUB, use the **HUB desktop** tab or run the HUB container from the **Docker** tab.

> **Verify the signing key (optional)**
>
> The key UID should show **Coreflux Portugal S.A. Package Signing** with email `packages@coreflux.org`:
>
> ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> gpg --no-default-keyring \
>   --keyring /usr/share/keyrings/coreflux-archive-keyring.gpg \
>   --list-keys --with-fingerprint
> ```

> **Manage the service**
>
> ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> sudo systemctl stop coreflux-broker
> sudo systemctl start coreflux-broker
> sudo systemctl restart coreflux-broker
> sudo journalctl -u coreflux-broker -f
> ```

**RPM (dnf)**

Use `dnf` on RHEL-compatible distributions—RHEL, Rocky Linux, AlmaLinux, and CentOS Stream. The repository uses `$releasever` and `$basearch`, so one repo file covers your EL version and CPU architecture (`x86_64` or `aarch64`).

| OS family | `$releasever` |
| - | - |
| EL 8 (RHEL / Rocky / Alma / CentOS Stream 8) | `8` |
| EL 9 (RHEL / Rocky / Alma / CentOS Stream 9) | `9` |
| EL 10 (RHEL / Rocky / Alma / CentOS Stream 10) | `10` |

**1. Import the signing key**

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
sudo rpm --import https://packages.coreflux.org/keys/coreflux.asc
```

**2. Add the repository**

Create `/etc/yum.repos.d/coreflux.repo`:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
printf '%s\n' \
  '[coreflux]' \
  'name=Coreflux stable (GA)' \
  'baseurl=https://packages.coreflux.org/rpm/el/$releasever/$basearch' \
  'enabled=1' \
  'gpgcheck=1' \
  'repo_gpgcheck=1' \
  'gpgkey=https://packages.coreflux.org/keys/coreflux.asc' \
  | sudo tee /etc/yum.repos.d/coreflux.repo
```

**3. Install coreflux-broker**

Refresh the package cache and install the broker:

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

Optional — list available versions before installing:

```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
dnf list --showduplicates coreflux-broker
```

**4. Confirm the service is running**

The package registers and starts `coreflux-broker` as a systemd service:

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

> [!TIP]
>
> **active (running)** means Coreflux is up. MQTT listens on port `1883` by default.

That's it—the broker is installed under `/opt/coreflux-broker` and managed by systemd. Confirm it works under [Verify Installation](#verify-installation) below. For the HUB, use the **HUB desktop** tab or run the HUB container from the **Docker** tab.

> **Manage the service**
>
> ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> sudo systemctl stop coreflux-broker
> sudo systemctl start coreflux-broker
> sudo systemctl restart coreflux-broker
> sudo journalctl -u coreflux-broker -f
> ```

***

## Verify Installation

The quickest visual check is the [Coreflux HUB](/hub/overview) in your browser. You can also confirm directly by connecting an MQTT client and seeing Coreflux's system topics—that's how the broker is actually used. Use the [default credentials](#default-login-credentials) from the top of the page (or your trial email).

**Coreflux HUB**

**1. Open the HUB**

Open your environment URL in the browser—for a **Cloud Trial**, use the address from your email; for **Docker** or **Docker Compose**, use `http://localhost:3000`. For the **HUB desktop** app, the window opens on its own.

![Coreflux HUB login screen with stored connections, Enter buttons, and New Connection](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/connections/hub-login-screen.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=1283b4df7650bbd9f90e518488441020)

**2. Choose or create a connection**

The login screen lists **stored connections**. Click **Enter** on a saved one, or click **New Connection** to add a broker.

Fill in the broker fields, then enter the [default credentials](#default-login-credentials) (or your trial email) and click **Connect**. Optionally click **Save connection** so the HUB remembers this broker next time.

| Install | Protocol | Host | Port | Path |
| - | - | - | - | - |
| Docker / Compose (broker + HUB) | `mqtt://` | `broker` | `1883` | — |
| Docker / Compose (WebSocket) | `ws://` | `broker` | `5000` | `mqtt` |
| HUB desktop, broker on this machine | `mqtt://` | `localhost` | `1883` | — |
| HUB-only container, broker on the host | `mqtt://` | `host.docker.internal` | `1883` | — |

![Coreflux HUB New Connection form with Local Hub, ws:// localhost port 5000 path mqtt, username root, Save connection, and Connect](https://mintcdn.com/coreflux/EldKmEArSuwejnkZ/images/connections/hub-login-setup.png?fit=max\&auto=format\&n=EldKmEArSuwejnkZ\&q=85\&s=63c5584209052080345ce3fdc8159511)

**3. Confirm the dashboard loaded**

After a successful login, you should see the HUB home screen with the bottom navigation bar.

![Coreflux HUB dashboard with Start here pointing to the first navigation icon](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/overview/hub-overview-start.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=bab525c05994ccb1c98530f1b50f40e1)

> [!TIP]
>
> The status bar shows route count and license info—the broker is reachable from the HUB.

**4. Browse MQTT data**

Select **MQTT** → **Data Viewer**. Expand **\$SYS/Coreflux** in the Topic Tree—you should see broker topics such as **Config**, **Version**, and **Resources** updating live.

![Coreflux HUB Data Viewer with Publish panel, Topic Tree, and tracked topic details](https://mintcdn.com/coreflux/7tBTxEEkDVX4IRGH/images/mqtt/data-viewer/mqtt-explorer-overview.png?fit=max\&auto=format\&n=7tBTxEEkDVX4IRGH\&q=85\&s=e9fdfa778a5c182a4c8a3404a3707f30)

**MQTT Client**

**1. Open MQTT Explorer**

Download [MQTT Explorer](https://mqtt-explorer.com/) or use any MQTT client of your choice.

**2. Connect to the Broker**

Create a new connection with these settings:

| Setting | Value |
| - | - |
| Host | `localhost` (or your trial URL host for Cloud Trial) |
| Port | `1883` (local Docker or Compose) or **8883** with MQTTS (Cloud Trial) |
| Username / Password | The default credentials above |

For **Cloud Trial**, use **MQTTS** on port **8883**, enable **Encryption**, and **disable Validate certificate** in MQTT Explorer.

**3. Check System Topics**

Subscribe to `$SYS/#` to see broker status messages. If you see topics such as `$SYS/Coreflux/Version`, the broker is running correctly.

> [!TIP]
>
> You should see Coreflux system topics under `$SYS/Coreflux/`.

### If verification fails

Pick the symptom that matches your setup:

> **All Versions — Broker isn't running or won't accept connections**
>
> If you can't connect, confirm the broker is actually up using the tooling for your install method.
>
> For a **Docker** install, inspect the container:
>
> ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
> # Is the container running?
> docker ps
>
> # View broker logs (live)
> docker logs -f coreflux_broker
>
> # View HUB logs (if you started the HUB container)
> docker logs -f coreflux_hub
>
> # Restart the container
> docker restart coreflux_broker
> ```
>
> For **Docker Compose**, use `docker compose ps` and `docker compose logs -f` from the directory that contains `docker-compose.yml`. The broker container is named `coreflux-broker`.
>
> For a **service install**, check the service status: `sudo systemctl status coreflux-broker` (Linux package install), `sudo systemctl status coreflux` (DigitalOcean droplet), or `sc query CorefluxBroker` (Windows).

> **Copy buttons don't work in the HUB**
>
> **Symptom:** copy buttons in a Docker or Docker Compose HUB do nothing, and nothing lands on the clipboard. This happens when you open the HUB over plain HTTP on a LAN IP or host name, for example `http://192.168.1.20:3000`.
>
> **Cause:** browsers only give pages clipboard access in a secure context, which means HTTPS or `localhost`. Current HUB versions have no fallback for plain HTTP.
>
> **Fix:** serve the HUB over HTTPS through a reverse proxy that terminates TLS (for example nginx, Caddy, or Traefik) and open the `https://` address. On the HUB's own machine, open `http://localhost:3000` instead. Until then, select the text and copy it with the keyboard. The desktop app is not affected.

> **All Versions — localhost doesn't load the HUB**
>
> **Symptom:** the HUB loads in some environments but not in a Docker-in-VM or remote setup.
>
> **Fix:** use the host's actual address instead of `localhost`.

> **Docker Only — Docker daemon not running**
>
> **Symptom:** the command errors with "cannot connect to the Docker daemon".
>
> **Fix:** start Docker Desktop (or the Docker service) and run the command again.

> **Docker Only — Port already in use**
>
> **Symptom:** an error binding a port, e.g. `3000` or `1883` is already allocated.
>
> **Fix:** stop the process using that port, or remap the host side of the port (for example `-p 1884:1883` on Docker, or change the left-hand port in `docker-compose.yml`).

> **Docker Only — Container exits immediately**
>
> **Symptom:** `docker ps` shows nothing after you start the broker.
>
> **Fix:** run `docker logs coreflux_broker` to see why it exited. For Compose, run `docker compose logs broker` from the directory that contains `docker-compose.yml`.

> **Docker Compose — HUB cannot reach the broker**
>
> **Symptom:** the HUB at `http://localhost:3000` fails to connect when **Host** is `localhost`, or shows **Broker isn't reachable**.
>
> **Fix:** the HUB proxies MQTT from inside Docker. On **New Connection**, set **Host** to `broker`, **Protocol** `mqtt://`, **Port** `1883` (or **Protocol** `ws://`, **Port** `5000`, **Path** `mqtt`).

> **Cloud Only — Can't connect to your trial**
>
> **Symptom:** the HUB or an MQTT client fails to connect right after you receive your trial email.
>
> **Fix:** wait up to **60 seconds** for the broker to become available, then retry. In the browser, allow **unsecure access** (or proceed past the certificate warning) for the trial URL. In MQTT Explorer, use **MQTTS** on port **8883**, enable **Encryption**, and **disable Validate certificate**.

***

## Next Steps

> **[Getting Started](/v2.14/quick-start/getting-started)**
>
> Create your first LoT Action in under 15 minutes.

> **[VS Code Extension](/v2.14/quick-start/vscode)**
>
> Set up the LoT language extension for syntax highlighting.


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