Installation

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)

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

Package manager installation (Linux)

CentOS

  1. Install the required dependencies
$ sudo yum install -y yum-utils device-mapper-persistent-data lvm2
  1. Set up a stable repository, taking the CentOS 7 as an example.
$ sudo yum-config-manager --add-repo https://repos.emqx.io/emqx-ce/redhat/centos/7/emqx-ce.repo
  1. Install the latest version of EMQ X
$ 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.

  1. Install a specific version of EMQ X

    1. Query available version
$ yum list emqx --showduplicates | sort -r

emqx.x86_64                     4.0.0-1.el7                        emqx-stable
emqx.x86_64                     3.0.1-1.el7                        emqx-stable
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

$ sudo yum install emqx-4.0.0

  1. Start EMQ X

    • Directly start
$ emqx start
emqx 4.0.0 is started successfully!

$ emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running

 * systemctl start

$ sudo systemctl start emqx

 * service start

$ sudo service emqx start
  1. Stop EMQ X Broker
$ emqx stop
ok
  1. Remove EMQ X Broker
$ sudo yum remove emqx

Ubuntu | Debian

  1. Install the required dependency
$ sudo apt update && sudo apt install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common
  1. Add the GPG key for EMQ X
$ curl -fsSL https://repos.emqx.io/gpg.pub | sudo apt-key add -

Validate key

$ sudo apt-key fingerprint 3E640D53

pub   rsa2048 2019-04-10 [SC]
    FC84 1BA6 3775 5CA8 487B  1E3C C0B4 0946 3E64 0D53
uid           [ unknown] emqx team <support@emqx.io>
  1. 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.
$ sudo add-apt-repository \
    "deb [arch=amd64] https://repos.emqx.io/emqx-ce/deb/ubuntu/ \
    ./$(lsb_release -cs) \
    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.

  1. Update apt package index
$ sudo apt update
  1. Install the latest version of EMQ X
$ 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.

  1. Install a specific version of EMQ X

    1. Query available version
$ sudo apt-cache madison emqx

emqx |      4.0.0 | https://repos.emqx.io/emqx-ce/deb/ubuntu bionic/stable amd64 Packages
emqx |      3.0.1 | https://repos.emqx.io/emqx-ce/deb/ubuntu bionic/stable amd64 Packages
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

$ sudo apt install emqx=4.0.0

  1. Start EMQ X Broker

    • Directly start
$ emqx start
emqx 4.0.0 is started successfully!

$ emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running

 * systemctl start

$ sudo systemctl start emqx

 * service start

$ sudo service emqx start
  1. Stop EMQ X Broker
$ emqx stop
ok
  1. Remove EMQ X Broker
$ sudo apt remove emqx

OpenSUSE

  1. Download the GPG public key and import it.
$ curl -L -o /tmp/gpg.pub https://repos.emqx.io/gpg.pub
$ sudo rpmkeys --import /tmp/gpg.pub
  1. Add repository address
$ sudo zypper ar -f -c https://repos.emqx.io/emqx-ce/redhat/opensuse/leap/stable emqx
  1. Install the latest version of EMQ X Broker
$ sudo zypper in emqx

  1. Install a specific version of EMQ X

    1. Query available versions
$ sudo zypper pa emqx

Loading repository data...
Reading installed packages...
S | Repository | Name | Version  | Arch
--+------------+------+----------+-------
  | emqx       | emqx | 4.0.0-1  | x86_64
  | emqx       | emqx | 3.0.1-1  | x86_64
  | emqx       | emqx | 3.0.0-1  | x86_64

 2. Install a specific version, such as 4.0.0

$ sudo zypper in emqx-4.0.0

  1. Start EMQ X Broker

    • Directly start
$ emqx start
emqx 4.0.0 is started successfully!

$ emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running

 * systemctl start

$ sudo systemctl start emqx

 * service start

$ sudo service emqx start
  1. Stop EMQ X Broker
$ emqx stop
ok
  1. Remove EMQ X Broker
$ sudo zypper rm emqx

Binary package installation (Linux)

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

  2. Install EMQ X Broker:

    • RPM 包:
$ sudo yum install emqx-cenots7-v4.0.0.x86_64.rpm

 * DEB package:

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

  1. Start EMQ X Broker

    • quick start
$ emqx start
emqx 4.0.0 is started successfully!
$ emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running

 * systemctl

$ sudo systemctl start emqx

 * start as service

$ sudo service emqx start
  1. Stop EMQ X Broker
$ emqx stop
ok

  1. Uninstall EMQ X Broker

    • DEB:
$ sudo apt remove --purge emqx

 * RPM:

$ sudo yum remove emqx

ZIP (Linux、MaxOS、Windows)

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

  2. Unzip the installation file:

$ unzip emqx-ubuntu18.04-v4.0.0.zip
  1. Start EMQ X Broker
$ ./bin/emqx start
emqx 4.0.0 is started successfully!

$ ./bin/emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running
  1. Stop EMQ X Broker
$ ./bin/emqx stop
ok
  1. Remove EMQ X Broker

Simply delete the EMQ X Broker directory

Install via Homebrew(MacOS)

  1. Add tap of EMQ X Broker
$ brew tap emqx/emqx
  1. Install EMQ X Broker
$ brew install emqx
  1. Start EMQ X Broker
$ emqx start
emqx 4.0.0 is started successfully!

$ emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running
  1. Stop EMQ X Broker
$ emqx stop
ok
  1. Uninstall EMQ X Broker
$ brew uninstall emqx

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

Run a single container

  1. Get docker image

$ docker pull emqx/emqx:v4.0.0

 * Download the Docker image from [emqx.io ![Installation - 图6](https://static.bookstack.cn/projects/emqx-broker-4.3-en/6b91bf1612fad5c40a0d54694e2c2f41.svg) (opens new window)](&lt;https://www.emqx.io/downloads/broker?osType=Linux>) or [Github ![Installation - 图7](https://static.bookstack.cn/projects/emqx-broker-4.3-en/6b91bf1612fad5c40a0d54694e2c2f41.svg) (opens new window)](&lt;https://github.com/emqx/emqx/releases>) and load it manually

$ wget -O emqx-docker.zip https://www.emqx.io/downloads/broker/v4.0.0/emqx-docker-v4.0.0-alpine3.10-amd64.zip
$ unzip emqx-docker.zip
$ docker load < emqx-docker-v4.0.0
  1. Start docker container
$ 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
version: '3'

services:
  emqx1:
    image: emqx/emqx:v4.0.0
    environment:
    - "EMQX_NAME=emqx"
    - "EMQX_HOST=node1.emqx.io"
    - "EMQX_CLUSTER__DISCOVERY=static"
    - "EMQX_CLUSTER__STATIC__SEEDS=emqx@node1.emqx.io, emqx@node2.emqx.io"
    - "EMQX_ZONE__EXTERNAL__RETRY_INTERVAL=2s"
    - "EMQX_MQTT__MAX_TOPIC_ALIAS=10"
    volumes:
        - ./tmp/emqx.lic:/opt/emqx/etc/emqx.lic
    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:v4.0.0
    environment:
    - "EMQX_NAME=emqx"
    - "EMQX_HOST=node2.emqx.io"
    - "EMQX_CLUSTER__DISCOVERY=static"
    - "EMQX_CLUSTER__STATIC__SEEDS=emqx@node1.emqx.io, emqx@node2.emqx.io"
    - "EMQX_ZONE__EXTERNAL__RETRY_INTERVAL=2s"
    - "EMQX_MQTT__MAX_TOPIC_ALIAS=10"
    volumes:
        - ./tmp/emqx.lic:/opt/emqx/etc/emqx.lic
    healthcheck:
      test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
      interval: 5s
      timeout: 25s
      retries: 5
    networks:
      emqx-bridge:
        aliases:
        - node2.emqx.io

  client:
    image: python:3.7.2-alpine3.9
    depends_on:
      - emqx1
      - emqx2
    tty: true
    networks:
        emqx-bridge:

networks:
  emqx-bridge:
    driver: bridge
  1. Start docker-compose cluster
$ docker-compose -p my_emqx up -d
  1. View cluster
$ docker exec -it my_emqx_emqx1_1 sh -c "emqx_ctl cluster status"
Cluster status: #{running_nodes => ['emqx@node1.emqx.io','emqx@node2.emqx.io'],
                  stopped_nodes => []}

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

Install and cluster via Helm (K8S、K3S)

  1. Add helm repository
$ helm repo add emqx https://repos.emqx.io/charts
$ helm repo update
  1. Query EMQ X Broker
helm search repo emqx
NAME         CHART VERSION APP VERSION DESCRIPTION
emqx/emqx    v4.0.0        v4.0.0      A Helm chart for EMQ X
emqx/emqx-ee v4.0.0        v4.0.0      A Helm chart for EMQ X
emqx/kuiper  0.1.1         0.1.1       A lightweight IoT edge analytic software
  1. Start EMQ X Broker cluster
$ helm install my-emqx emqx/emqx
  1. View EMQ X Broker 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 => []}

Source code compilation and installation

  1. Get the source code
$ git clone https://github.com/emqx/emqx.git
  1. Checkout to latest tag
$ cd emqx
$ git checkout $(git describe --abbrev=0 --tags)
  1. Compile
$ make
  1. Start EMQ X Broker
$ cd _build/emqx/rel/emqx

$ ./bin/emqx start
EMQ X Broker 4.3-beta.1 is started successfully!

$ ./bin/emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx 4.3-beta.1 is running