Installation

Operating systems currently supported by EMQ X Broker:

  • CentOS 6
  • CentOS 7
  • CentOS 8
  • OpenSUSE tumbleweed
  • Debian 8
  • Debian 9
  • Debian 10
  • Ubuntu 14.04
  • Ubuntu 16.04
  • Ubuntu 18.04
  • Ubuntu 20.04
  • macOS 10.13
  • macOS 10.14
  • macOS 10.15
  • Windows Server 2019

One-click installation of shell script (Linux)

  1. curl https://repos.emqx.io/install_emqx.sh | bash

Package manager installation (Linux)

CentOS

  1. Install the required dependencies

    1. $ sudo yum install -y yum-utils device-mapper-persistent-data lvm2

  2. Set up a stable repository, taking the CentOS 7 as an example.

    1. $ sudo yum-config-manager --add-repo https://repos.emqx.io/emqx-ce/redhat/centos/7/emqx-ce.repo

  3. Install the latest version of EMQ X

    1. $ sudo yum install emqx

    If prompted to accept the GPG key, confirm that the key complies with fc84 1ba6 3775 5ca8 487b 1e3c c0b4 0946 3e64 0d53 and accept the fingerprint.

  4. Install a specific version of EMQ X

    1. Query available version

      1. $ yum list emqx --showduplicates | sort -r
      3. emqx.x86_64                     4.0.0-1.el7                        emqx-stable
      4. emqx.x86_64                     3.0.1-1.el7                        emqx-stable
      5. emqx.x86_64                     3.0.0-1.el7                        emqx-stable

    2. Install a specific version based on the version string in the second column, such as 4.0.0

      1. $ sudo yum install emqx-4.0.0

  5. Start EMQ X

    • Directly start

      1. $ emqx start
      2. emqx 4.0.0 is started successfully!
      4. $ emqx_ctl status
      5. Node 'emqx@127.0.0.1' is started
      6. emqx v4.0.0 is running

    • systemctl start

      1. $ sudo systemctl start emqx

    • service start

      1. $ sudo service emqx start

  6. Stop EMQ X Broker

    1. $ emqx stop
    2. ok

  7. Remove EMQ X Broker

    1. $ sudo yum remove emqx

Ubuntu | Debian

  1. Install the required dependency

    1. $ sudo apt update && sudo apt install -y \
    2.     apt-transport-https \
    3.     ca-certificates \
    4.     curl \
    5.     gnupg-agent \
    6.     software-properties-common

  2. Add the GPG key for EMQ X

    1. $ curl -fsSL https://repos.emqx.io/gpg.pub | sudo apt-key add -

    Validate key

    1. $ sudo apt-key fingerprint 3E640D53
    3. pub   rsa2048 2019-04-10 [SC]
    4.     FC84 1BA6 3775 5CA8 487B  1E3C C0B4 0946 3E64 0D53
    5. uid           [ unknown] emqx team <support@emqx.io>

  3. Use the following command to set up the stable repository. If unstable repo is also needed, add the word ‘unstable’ after ‘stable’ in the following command.

    1. $ sudo add-apt-repository \
    2.     "deb [arch=amd64] https://repos.emqx.io/emqx-ce/deb/ubuntu/ \
    3.     ./$(lsb_release -cs) \
    4.     stable"

    The lsb_release -cs subcommand returns the name of the Ubuntu distribution, such as xenial. Sometimes, in a distribution like Linux Mint, you might need to change $(lsb_release -cs) to the parent Ubuntu distribution. For example, if you are using Linux Mint Tessa, you can use bionic. EMQ X does not provide any guarantees for untested and unsupported Ubuntu distribution.

  4. Update apt package index

    1. $ sudo apt update

  5. Install the latest version of EMQ X

    1. $ sudo apt install emqx

    In the case where multiple EMQ X repositories are enabled, and the apt install and apt update commands is not specified with a version number, the latest version of EMQ X is installed. This could be a problem for users with stability needs.

  6. Install a specific version of EMQ X

    1. Query available version

      1. $ sudo apt-cache madison emqx
      3. emqx |      4.0.0 | https://repos.emqx.io/emqx-ce/deb/ubuntu bionic/stable amd64 Packages
      4. emqx |      3.0.1 | https://repos.emqx.io/emqx-ce/deb/ubuntu bionic/stable amd64 Packages
      5. emqx |      3.0.0 | https://repos.emqx.io/emqx-ce/deb/ubuntu bionic/stable amd64 Packages

    2. Install a specific version using the version string from the second column, such as 4.0.0

      1. $ sudo apt install emqx=4.0.0

  7. Start EMQ X Broker

    • Directly start

      1. $ emqx start
      2. emqx 4.0.0 is started successfully!
      4. $ emqx_ctl status
      5. Node 'emqx@127.0.0.1' is started
      6. emqx v4.0.0 is running

    • systemctl start

      1. $ sudo systemctl start emqx

    • service start

      1. $ sudo service emqx start

  8. Stop EMQ X Broker

    1. $ emqx stop
    2. ok

  9. Remove EMQ X Broker

    1. $ sudo apt remove emqx

OpenSUSE

  1. Download the GPG public key and import it.

    1. $ curl -L -o /tmp/gpg.pub https://repos.emqx.io/gpg.pub
    2. $ sudo rpmkeys --import /tmp/gpg.pub

  2. Add repository address

    1. $ sudo zypper ar -f -c https://repos.emqx.io/emqx-ce/redhat/opensuse/leap/stable emqx

  3. Install the latest version of EMQ X Broker

    1. $ sudo zypper in emqx

  4. Install a specific version of EMQ X

    1. Query available versions

      1. $ sudo zypper pa emqx
      3. Loading repository data...
      4. Reading installed packages...
      5. S | Repository | Name | Version  | Arch
      6. --+------------+------+----------+-------
      7.   | emqx       | emqx | 4.0.0-1  | x86_64
      8.   | emqx       | emqx | 3.0.1-1  | x86_64
      9.   | emqx       | emqx | 3.0.0-1  | x86_64

    2. Install a specific version, such as 4.0.0

      1. $ sudo zypper in emqx-4.0.0

  5. Start EMQ X Broker

    • Directly start

      1. $ emqx start
      2. emqx 4.0.0 is started successfully!
      4. $ emqx_ctl status
      5. Node 'emqx@127.0.0.1' is started
      6. emqx v4.0.0 is running

    • systemctl start

      1. $ sudo systemctl start emqx

    • service start

      1. $ sudo service emqx start

  6. Stop EMQ X Broker

    1. $ emqx stop
    2. ok

  7. Remove EMQ X Broker

    1. $ sudo zypper rm emqx

Binary package installation (Linux)

  1. Use emqx.ioInstallation - 图1 (opens new window) or GithubInstallation - 图2 (opens new window) for download EMQ X Broker packages。

  2. Install EMQ X Broker:

    • RPM 包:

      1. $ sudo yum install emqx-cenots7-v4.0.0.x86_64.rpm

    • DEB package:

      1. # for ubuntu/debian
      2. $ sudo apt install ./emqx-ubuntu18.04-v4.0.0_amd64.deb
      3. $ sudo apt install ./emqx-debian10-v4.0.0_amd64.deb

  3. Start EMQ X Broker

    • quick start

      1. $ emqx start
      2. emqx 4.0.0 is started successfully!
      3. $ emqx_ctl status
      4. Node 'emqx@127.0.0.1' is started
      5. emqx v4.0.0 is running

    • systemctl

      1. $ sudo systemctl start emqx

    • start as service

      1. $ sudo service emqx start

  4. Stop EMQ X Broker

    1. $ emqx stop
    2. ok

  5. Uninstall EMQ X Broker

    • DEB:

      1. $ sudo apt remove --purge emqx

    • RPM:

      1. $ sudo yum remove emqx

ZIP (Linux、MaxOS、Windows)

  1. Download the zip package of the EMQ X Broker version to be installed from emqx.ioInstallation - 图3 (opens new window) or GithubInstallation - 图4 (opens new window).

  2. Unzip the installation file:

    1. $ unzip emqx-ubuntu18.04-v4.0.0.zip

  3. Start EMQ X Broker

    1. $ ./bin/emqx start
    2. emqx 4.0.0 is started successfully!
    4. $ ./bin/emqx_ctl status
    5. Node 'emqx@127.0.0.1' is started
    6. emqx v4.0.0 is running

  4. Stop EMQ X Broker

    1. $ ./bin/emqx stop
    2. ok

  5. Remove EMQ X Broker

    Simply delete the EMQ X Broker directory

Install via Homebrew(MacOS)

  1. Add tap of EMQ X Broker

    1. $ brew tap emqx/emqx

  2. Install EMQ X Broker

    1. $ brew install emqx

  3. Start EMQ X Broker

    1. $ emqx start
    2. emqx 4.0.0 is started successfully!
    4. $ emqx_ctl status
    5. Node 'emqx@127.0.0.1' is started
    6. emqx v4.0.0 is running

  4. Stop EMQ X Broker

    1. $ emqx stop
    2. ok

  5. Uninstall EMQ X Broker

    1. $ brew uninstall emqx

Install EMQ X in Docker (Contain a simple docker-compose cluster)

Run a single container

  1. Get docker image

  2. Start docker container

    1. $ docker run -d --name emqx -p 1883:1883 -p 8081:8081 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 18083:18083 emqx/emqx:v4.0.0

create a simple static cluster by docker-compose

  1. Create docker-compose.yaml file

    1. version: '3'
    3. services:
    4.   emqx1:
    5.     image: emqx/emqx:v4.0.0
    6.     environment:
    7.     - "EMQX_NAME=emqx"
    8.     - "EMQX_HOST=node1.emqx.io"
    9.     - "EMQX_CLUSTER__DISCOVERY=static"
    10.     - "EMQX_CLUSTER__STATIC__SEEDS=emqx@node1.emqx.io, emqx@node2.emqx.io"
    11.     - "EMQX_ZONE__EXTERNAL__RETRY_INTERVAL=2s"
    12.     - "EMQX_MQTT__MAX_TOPIC_ALIAS=10"
    13.     volumes:
    14.         - ./tmp/emqx.lic:/opt/emqx/etc/emqx.lic
    15.     healthcheck:
    16.       test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
    17.       interval: 5s
    18.       timeout: 25s
    19.       retries: 5
    20.     networks:
    21.       emqx-bridge:
    22.         aliases:
    23.         - node1.emqx.io
    25.   emqx2:
    26.     image: emqx/emqx:v4.0.0
    27.     environment:
    28.     - "EMQX_NAME=emqx"
    29.     - "EMQX_HOST=node2.emqx.io"
    30.     - "EMQX_CLUSTER__DISCOVERY=static"
    31.     - "EMQX_CLUSTER__STATIC__SEEDS=emqx@node1.emqx.io, emqx@node2.emqx.io"
    32.     - "EMQX_ZONE__EXTERNAL__RETRY_INTERVAL=2s"
    33.     - "EMQX_MQTT__MAX_TOPIC_ALIAS=10"
    34.     volumes:
    35.         - ./tmp/emqx.lic:/opt/emqx/etc/emqx.lic
    36.     healthcheck:
    37.       test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
    38.       interval: 5s
    39.       timeout: 25s
    40.       retries: 5
    41.     networks:
    42.       emqx-bridge:
    43.         aliases:
    44.         - node2.emqx.io
    46.   client:
    47.     image: python:3.7.2-alpine3.9
    48.     depends_on:
    49.       - emqx1
    50.       - emqx2
    51.     tty: true
    52.     networks:
    53.         emqx-bridge:
    55. networks:
    56.   emqx-bridge:
    57.     driver: bridge

  2. Start docker-compose cluster

    1. $ docker-compose -p my_emqx up -d

  3. View cluster

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

For more information about EMQ X Broker Docker, please visit Docker HubInstallation - 图8 (opens new window) or GithubInstallation - 图9 (opens new window)

Install and cluster via Helm (K8S、K3S)

  1. Add helm repository
  1. $ helm repo add emqx https://repos.emqx.io/charts
  2. $ helm repo update
  1. Query EMQ X Broker
  1. helm search repo emqx
  2. NAME         CHART VERSION APP VERSION DESCRIPTION
  3. emqx/emqx    v4.0.0        v4.0.0      A Helm chart for EMQ X
  4. emqx/emqx-ee v4.0.0        v4.0.0      A Helm chart for EMQ X
  5. emqx/kuiper  0.1.1         0.1.1       A lightweight IoT edge analytic software
  1. Start EMQ X Broker cluster
  1. $ helm install my-emqx emqx/emqx
  1. View EMQ X Broker cluster situation
  1. $ kubectl get pods
  2. NAME       READY  STATUS             RESTARTS  AGE
  3. my-emqx-0  1/1     Running   0          56s
  4. my-emqx-1  1/1     Running   0          40s
  5. my-emqx-2  1/1     Running   0          21s
  7. $ kubectl exec -it my-emqx-0 -- emqx_ctl cluster status
  8. Cluster status: #{running_nodes =>
  9.                       ['my-emqx@my-emqx-0.my-emqx-headless.default.svc.cluster.local',
  10.                        'my-emqx@my-emqx-1.my-emqx-headless.default.svc.cluster.local',
  11.                        'my-emqx@my-emqx-2.my-emqx-headless.default.svc.cluster.local'],
  12.                   stopped_nodes => []}

Source code compilation and installation

  1. Get the source code
  1. $ git clone https://github.com/emqx/emqx.git
  1. Checkout to latest tag
  1. $ cd emqx
  2. $ git checkout $(git describe --abbrev=0 --tags)
  1. Compile
  1. $ make
  1. Start EMQ X Broker
  1. $ cd _build/emqx/rel/emqx
  3. $ ./bin/emqx start
  4. EMQ X Broker 4.3-beta.1 is started successfully!
  6. $ ./bin/emqx_ctl status
  7. Node 'emqx@127.0.0.1' is started
  8. emqx 4.3-beta.1 is running