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

> Install Coreflux on your preferred platform — Cloud Trial, Docker, Windows, Linux, or Raspberry Pi.

## Why Install Locally?

Running Coreflux on your own machine gives you a complete IoT data pipeline—MQTT broker, LoT runtime, and data routing—without external dependencies. Prefer zero setup? Start with a **Cloud Trial** and connect MQTT clients to the hosted broker.

<Tip>
  **Coreflux runs as a single binary or container.** No databases, no message queues, no orchestration needed—just download and run.
</Tip>

***

## Install Coreflux

<Tabs>
  <Tab title="Cloud Trial" icon="sparkles">
    Get a hosted Coreflux broker without installing anything. Request a trial on the [Coreflux website](https://www.coreflux.org/), and you will receive an email with the **broker host** and **MQTT credentials**.

    <Steps>
      <Step title="Request a trial">
        Go to [coreflux.org](https://www.coreflux.org/) and submit a trial request using the form on the site.
      </Step>

      <Step title="Check your email">
        When your environment is ready, Coreflux sends an email with:

        | Item            | What you use it for                                                                                              |
        | --------------- | ---------------------------------------------------------------------------------------------------------------- |
        | **Host / URL**  | MQTT broker address (use this hostname in MQTT Explorer or the [VS Code extension](/v1.10.0/quick-start/vscode)) |
        | **Credentials** | Username and password for MQTT clients                                                                           |

        <Note>
          The broker may take **up to 60 seconds** to be fully available after you receive the email. If the MQTT connection fails immediately, wait briefly and try again.
        </Note>
      </Step>

      <Step title="Connect MQTT clients">
        Use the host from 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).
      </Step>
    </Steps>

    <Tip>
      Continue with [Getting Started](/v1.10.0/quick-start/getting-started) using the **VS Code Extension** or **MQTT Client** tabs to deploy your first LoT Action.
    </Tip>
  </Tab>

  <Tab title="Docker" icon="docker">
    Docker is the fastest way to get Coreflux running. The official image works on Linux, macOS, and Windows. Pull the image from [Docker Hub](https://hub.docker.com/r/coreflux/coreflux-mqtt-broker) or open a terminal and run the command below—Docker will pull automatically if the image is not present.

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    docker run -d --name coreflux_broker -p 1883:1883 -p 5000:5000 coreflux/coreflux-mqtt-broker:latest
    ```

    | Port   | Protocol  | Description           |
    | ------ | --------- | --------------------- |
    | `1883` | TCP       | MQTT (unencrypted)    |
    | `5000` | WebSocket | WebSocket connections |

    <Note>
      New to Docker? Visit the [official Docker documentation](https://docs.docker.com/get-started/) to learn more.
    </Note>

    <AccordionGroup>
      <Accordion title="Coreflux HUB (beta) — optional Docker install">
        **Coreflux HUB** is in beta for this release. It is not included in the default broker-only install above. To run the broker **with the HUB beta UI**, publish ports `8080` (HTTP) and `8443` (HTTPS) and use the same image:

        ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
        docker run -d --name coreflux_broker -p 1883:1883 -p 5000:5000 -p 8080:8080 -p 8443:8443 coreflux/coreflux-mqtt-broker:latest
        ```

        | Port   | Protocol | Description                      |
        | ------ | -------- | -------------------------------- |
        | `8080` | HTTP     | Coreflux HUB (beta, unencrypted) |
        | `8443` | HTTPS    | Coreflux HUB (beta, TLS)         |

        After the container starts, open `http://localhost:8080` or `https://localhost:8443`. HUB features and UI may change while in beta.
      </Accordion>

      <Accordion title="TLS/SSL Ports (when using certificates)">
        If you configure TLS certificates, expose these additional ports on the broker-only command:

        ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
        docker run -d --name coreflux_broker -p 1883:1883 -p 5000:5000 -p 8883:8883 -p 443:443 coreflux/coreflux-mqtt-broker:latest
        ```

        With **HUB beta**, add `8080`, `8443`, and the TLS ports in one run:

        ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
        docker run -d --name coreflux_broker -p 1883:1883 -p 5000:5000 -p 8080:8080 -p 8443:8443 -p 8883:8883 -p 443:443 coreflux/coreflux-mqtt-broker:latest
        ```

        | Port   | Protocol | Description        |
        | ------ | -------- | ------------------ |
        | `8883` | TCP/TLS  | MQTT over TLS      |
        | `443`  | WSS      | WebSocket over TLS |

        See [Broker Configuration](/v1.10.0/mqtt-broker/configuration) for TLS setup.
      </Accordion>
    </AccordionGroup>
  </Tab>

  <Tab title="DigitalOcean" icon="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.

    <a href="https://marketplace.digitalocean.com/apps/coreflux-mqtt-broker?refcode=b993040d0243&action=deploy" target="_blank">
      <img src="https://mintcdn.com/coreflux/A0D_IE52Pl2ItO0u/do/buttons/do-btn-blue.svg?fit=max&auto=format&n=A0D_IE52Pl2ItO0u&q=85&s=f267478fefd55a7e41d52153947a2d65" alt="Deploy to DigitalOcean" width="200" noZoom data-path="do/buttons/do-btn-blue.svg" />
    </a>

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

      <Step title="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.
        </Tip>
      </Step>

      <Step title="Select Region">
        Choose a datacenter close to your devices for lower latency.
      </Step>

      <Step title="Create Droplet">
        Click **Create Droplet** and wait \~60 seconds for deployment.
      </Step>

      <Step title="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`          |
      </Step>
    </Steps>

    <Warning>
      Change the default password immediately after first login. SSH into your droplet and update the broker configuration.
    </Warning>

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

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

  <Tab title="Windows" icon="windows">
    Download and install Coreflux, then register it as a Windows service using the native `sc` tool.

    1. Download the Windows zip from the [Coreflux website](https://www.coreflux.org) (**Start Free**)
    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
    ```

    The service is now registered, set to start automatically on boot, and running.

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

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

  <Tab title="Linux" icon="linux">
    Download and run the Coreflux binary on Linux x64 systems.

    **Quick Start (foreground):**

    1. Download the Linux zip from the [Coreflux website](https://www.coreflux.org) (**Start Free**)
    2. Extract and run (replace `<downloaded-file>` with your actual filename):

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    unzip <downloaded-file>.zip -d coreflux
    cd coreflux
    chmod +x CorefluxMQTTBroker
    ./CorefluxMQTTBroker
    ```

    **Production Setup (systemd service):**

    1. Create a service file:

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    sudo nano /etc/systemd/system/coreflux.service
    ```

    2. Add this configuration (adjust paths as needed):

    ```ini wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    [Unit]
    Description=Coreflux MQTT Broker
    After=network.target

    [Service]
    Type=simple
    User=root
    WorkingDirectory=/opt/coreflux
    ExecStart=/opt/coreflux/CorefluxMQTTBroker
    Restart=always
    RestartSec=5

    [Install]
    WantedBy=multi-user.target
    ```

    3. Enable and start the service:

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

    4. Check the status:

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

  <Tab title="Raspberry Pi" icon="raspberry-pi">
    Download and run the Coreflux binary on Raspberry Pi (64-bit ARM).

    **Quick Start (foreground):**

    1. Download the Raspberry Pi zip from the [Coreflux website](https://www.coreflux.org) (**Start Free**)
    2. Extract and run (replace `<downloaded-file>` with your actual filename):

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    unzip <downloaded-file>.zip -d coreflux
    cd coreflux
    chmod +x CorefluxMQTTBroker
    ./CorefluxMQTTBroker
    ```

    **Production Setup (systemd service):**

    1. Create a service file:

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    sudo nano /etc/systemd/system/coreflux.service
    ```

    2. Add this configuration:

    ```ini wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    [Unit]
    Description=Coreflux MQTT Broker
    After=network.target

    [Service]
    Type=simple
    User=root
    WorkingDirectory=/home/pi/coreflux
    ExecStart=/home/pi/coreflux/CorefluxMQTTBroker
    Restart=always
    RestartSec=5

    [Install]
    WantedBy=multi-user.target
    ```

    3. Enable and start the service:

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

    4. Check the status:

    ```bash wrap theme={"theme":"css-variables","languages":{"custom":["/languages/lot.json"]}}
    sudo systemctl status coreflux
    ```
  </Tab>
</Tabs>

***

## Verify Installation

Confirm the broker is running with an MQTT client (or the [VS Code LoT extension](/v1.10.0/quick-start/vscode)).

<Tabs>
  <Tab title="MQTT Explorer" icon="terminal">
    <Steps>
      <Step title="Open MQTT Explorer">
        Download [MQTT Explorer](https://mqtt-explorer.com/) or use any MQTT client of your choice.
      </Step>

      <Step title="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 **8883** with MQTTS (Cloud Trial) |
        | Username | `root` (or credentials from your trial email)              |
        | Password | `coreflux` (or credentials from your trial email)          |

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

      <Step title="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.

        <Check>
          You should see Coreflux system topics under `$SYS/Coreflux/`.
        </Check>
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Getting Started" icon="rocket" href="/v1.10.0/quick-start/getting-started">
    Create your first LoT Action in under 15 minutes.
  </Card>

  <Card title="VS Code Extension" icon="code" href="/v1.10.0/quick-start/vscode">
    Set up the LoT language extension for syntax highlighting.
  </Card>
</CardGroup>