> ## 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 - 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 or cloud subscriptions.

<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="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 theme={null}
    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="TLS/SSL Ports (when using certificates)">
        If you configure TLS certificates, expose these additional ports:

        ```bash theme={null}
        docker run -d --name coreflux_broker -p 1883:1883 -p 5000:5000 -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](/mqtt-broker/configuration) for TLS setup.
      </Accordion>

      <Accordion title="Coreflux HUB Ports">
        To enable the Coreflux HUB, expose these additional ports:

        ```bash theme={null}
        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     | HUB (unencrypted) |
        | `8443` | HTTPS    | HUB (TLS)         |

        <Note>
          If these ports are not specified, the broker runs normally but without the HUB. See [Coreflux HUB Overview](/coreflux-hub/overview) to learn more.
        </Note>
      </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 theme={null}
        ssh root@<your-droplet-ip>
        ```

        The Coreflux broker runs as a systemd service. Common commands:

        ```bash theme={null}
        # 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 [coreflux.org/downloads](https://www.coreflux.org/downloads)
    2. Extract the zip file to your preferred location (e.g., `C:\Coreflux`)
    3. Open Command Prompt **as Administrator** and run:

    ```cmd theme={null}
    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 theme={null}
        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 theme={null}
        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 [coreflux.org/downloads](https://www.coreflux.org/downloads)
    2. Extract and run (replace `<downloaded-file>` with your actual filename):

    ```bash theme={null}
    unzip <downloaded-file>.zip -d coreflux
    cd coreflux
    chmod +x CorefluxMQTTBroker
    ./CorefluxMQTTBroker
    ```

    **Production Setup (systemd service):**

    1. Create a service file:

    ```bash theme={null}
    sudo nano /etc/systemd/system/coreflux.service
    ```

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

    ```ini theme={null}
    [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 theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable coreflux
    sudo systemctl start coreflux
    ```

    4. Check the status:

    ```bash theme={null}
    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 [coreflux.org/downloads](https://www.coreflux.org/downloads)
    2. Extract and run (replace `<downloaded-file>` with your actual filename):

    ```bash theme={null}
    unzip <downloaded-file>.zip -d coreflux
    cd coreflux
    chmod +x CorefluxMQTTBroker
    ./CorefluxMQTTBroker
    ```

    **Production Setup (systemd service):**

    1. Create a service file:

    ```bash theme={null}
    sudo nano /etc/systemd/system/coreflux.service
    ```

    2. Add this configuration:

    ```ini theme={null}
    [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 theme={null}
    sudo systemctl daemon-reload
    sudo systemctl enable coreflux
    sudo systemctl start coreflux
    ```

    4. Check the status:

    ```bash theme={null}
    sudo systemctl status coreflux
    ```
  </Tab>
</Tabs>

***

## Verify Installation

Confirm the broker is running by connecting with an MQTT client and subscribing to a system topic.

<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` |
    | Port     | `1883`      |
    | Username | `root`      |
    | Password | `coreflux`  |
  </Step>

  <Step title="Check System Topics">
    Subscribe to `$SYS/#` to see broker status messages. If you see topics like `$SYS/broker/version`, the broker is running correctly.

    <Check>
      You should see the Coreflux version number published to `$SYS/broker/version`.
    </Check>
  </Step>
</Steps>

***

## Next Steps

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

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