# Installation

EMQX binary packages are released on the below operating systems:

  • EL7 (RedHat 7, CentOS 7)
  • EL8 (RedHat 8, RockyLinux 8, AmazonLinux 2022)
  • Raspbian 10
  • Debian 9
  • Debian 10
  • Debian 11
  • Ubuntu 16.04
  • Ubuntu 18.04
  • Ubuntu 20.04
  • macOS 11
  • Windows Server 2019

For EL8 and Ubuntu 20.04 there are also packages built with Elixir (opens new window)'s Mix (opens new window). They support plugins written in Elixir and have debug console powered with IEx (opens new window).

# Running EMQX in Docker

# Run a single container

  1. Get docker image

    docker pull emqx/emqx:5.0.9
    
    1
  2. Start docker container

    docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 18083:18083 emqx/emqx:5.0.9
    
    1

# Create a simple static cluster by docker-compose

  1. Create docker-compose.yaml file

    version: '3'
    
    services:
      emqx1:
        image: emqx/emqx:5.0.9
        container_name: emqx1
        environment:
        - "EMQX_NODE_NAME=emqx@node1.emqx.io"
        - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
        - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io,emqx@node2.emqx.io]"
        healthcheck:
          test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
          interval: 5s
          timeout: 25s
          retries: 5
        networks:
          emqx-bridge:
            aliases:
            - node1.emqx.io
    
      emqx2:
        image: emqx/emqx:5.0.9
        container_name: emqx2
        environment:
        - "EMQX_NODE_NAME=emqx@node2.emqx.io"
        - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
        - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io,emqx@node2.emqx.io]"
        healthcheck:
          test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
          interval: 5s
          timeout: 25s
          retries: 5
        networks:
          emqx-bridge:
            aliases:
            - node2.emqx.io
    
    networks:
      emqx-bridge:
        driver: bridge
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
  2. Start docker-compose cluster

    docker-compose up -d
    
    1
  3. View cluster

    $ docker exec -it emqx1 sh -c "emqx_ctl cluster status"
    Cluster status: #{running_nodes => ['emqx@node1.emqx.io','emqx@node2.emqx.io'],
                      stopped_nodes => []}
    
    1
    2
    3

For more information about EMQX Docker please visit Docker Hub (opens new window) or Github (opens new window)

# Package Installation (Linux)

WARING

EMQX starts as emqx@127.0.0.1 by default, and the node name will be written as a part of the built-in database. Purge database directory /var/lib/emqx/data/mnesia before starting it with a different name.

  1. Download EMQX package emqx.io (opens new window) or Github (opens new window)
  1. Install EMQX:

    • RPM package (RedHat/CentOS/RockyLinux/AmazonLinux):

      sudo yum install path/to/emqx-full-package-name.rpm
      
      1
    • DEB package (Ubuntu/Debian/Raspbian):

      sudo apt install path/to/emqx-full-package-name.deb
      
      1
  2. Start EMQX and check the status

    • quick start

      sudo su - emqx
      emqx start
      emqx_ctl status
      
      1
      2
      3
    • systemctl

      sudo systemctl start emqx
      
      1
  3. Stop EMQX

    $ emqx stop
    
    1
  4. Uninstall EMQX

    • DEB:

      sudo apt remove --purge emqx
      
      1
    • RPM:

      sudo yum remove emqx
      
      1

# tar.gz (Linux, macOS, Windows)

WARING

tar.gz packages are released for quick testing and hot-beam upgrades. Do NOT install tar.gz packages for production unless you know how to manually resolve all the runtime dependencies.

  1. Download EMQX package emqx.io (opens new window) or Github (opens new window)
  1. Extract the package:

    tar -zxf emqx-full-package-name.tar.gz
    
    1
  2. Start EMQX and check the status

    ./bin/emqx start
    ./bin/emqx_ctl status
    
    1
    2
  3. Stop EMQX

    ./bin/emqx stop
    
    1
  4. Remove EMQX

    Simply delete the EMQX directory

# Install and cluster via Helm (K8S, K3S)

  1. Add helm repository
helm repo add emqx https://repos.emqx.io/charts
helm repo update
1
2
  1. Query EMQX
$ helm search repo emqx
NAME                CHART VERSION APP VERSION DESCRIPTION
emqx/emqx           5.0.9         5.0.9       A Helm chart for EMQX
emqx/emqx-ee        4.4.5         4.4.5       A Helm chart for EMQ X
emqx/emqx-operator  1.0.7         1.2.2       A Helm chart for EMQX Operator Controller
emqx/kuiper         0.9.0         0.9.0       A lightweight IoT edge analytic software
1
2
3
4
5
6
  1. Start EMQX cluster
helm install my-emqx emqx/emqx
1
  1. View EMQX cluster situation
$ kubectl get pods
NAME       READY  STATUS             RESTARTS  AGE
my-emqx-0  1/1     Running   0          56s
my-emqx-1  1/1     Running   0          40s
my-emqx-2  1/1     Running   0          21s

$ kubectl exec -it my-emqx-0 -- emqx_ctl cluster status
Cluster status: #{running_nodes =>
                      ['my-emqx@my-emqx-0.my-emqx-headless.default.svc.cluster.local',
                       'my-emqx@my-emqx-1.my-emqx-headless.default.svc.cluster.local',
                       'my-emqx@my-emqx-2.my-emqx-headless.default.svc.cluster.local'],
                  stopped_nodes => []}
1
2
3
4
5
6
7
8
9
10
11
12

# Source code compilation and installation

  1. Get the source code
git clone https://github.com/emqx/emqx.git
1
  1. Checkout to latest tag
cd emqx
git checkout $(git describe --abbrev=0 --tags)
1
2
  1. Compile and run
make run
1