Installation

Operating systems currently supported by EMQ X Broker:

Centos6
Centos7
OpenSUSE tumbleweed
Debian 8
Debian 9
Debian 10
Ubuntu 14.04
Ubuntu 16.04
Ubuntu 18.04
macOS 10.13
macOS 10.14
macOS 10.15
Windows Server 2019

One-click installation of shell script (Linux)

bash

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

Package manager installation (Linux)

Centos

Install the required dependencies

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

Set up a stable repository, taking the CentOS7 as an example.

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

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.

Install a specific version of EMQ X

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

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

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

Stop EMQ X Broker
```
$ emqx stop
ok
```
Remove EMQ X Broker
```
$ sudo yum remove emqx
```

Ubuntu、Debian

Install the required dependency

$ sudo apt update && sudo apt install -y \
    apt-transport-https \
    ca-certificates \
    curl \
    gnupg-agent \
    software-properties-common

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>

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.
Update apt package index
```
$ sudo apt update
```
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.

Install a specific version of EMQ X

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

Install a specific version using the version string from the second column, such as 4.0.0
```
$ sudo apt install emqx=4.0.0
```

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

Stop EMQ X Broker
```
$ emqx stop
ok
```
Remove EMQ X Broker
```
$ sudo apt remove emqx
```

OpenSUSE

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

Add repository address

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

Install the latest version of EMQ X Broker
```
$ sudo zypper in emqx
```

Install a specific version of EMQ X

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

Install a specific version, such as 4.0.0
```
$ sudo zypper in emqx-4.0.0
```

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

Stop EMQ X Broker
```
$ emqx stop
ok
```
Remove EMQ X Broker
```
$ sudo zypper rm emqx
```

Binary package installation (Linux)

Use emqx.io or Github for download EMQ X Broker packages。

Install EMQ X Broker:

RPM 包:

shell

$ sudo rpm -ivh emqx-cenots7-v4.0.0.x86_64.rpm

DEB 包:

$ sudo dpkg -i emqx-ubuntu18.04-v4.0.0_amd64.deb

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

Stop EMQ X Broker
```
$ emqx stop
ok
```

Uninstall EMQ X Broker

DEB:
```
$ dpkg -r emqx
```
or
```
$ dpkg -P emqx
```
RPM:
```
$ rpm -e emqx
```

ZIP (Linux、MaxOS、Windows)

Download the zip package of the EMQ X Broker version to be installed from emqx.io or Github.
Unzip the installation file:
shell
```
$ unzip emqx-ubuntu18.04-v4.0.0.zip
```

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

Stop EMQ X Broker
```
$ ./bin/emqx stop
ok
```
Remove EMQ X Broker
Simply delete the EMQ X Broker directory

Install via Homebrew(MacOS)

Add tap of EMQ X Broker
```
$ brew tap emqx/emqx
```
Install EMQ X Broker
```
$ brew install emqx
```

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

Stop EMQ X Broker
```
$ emqx stop
ok
```
Uninstall EMQ X Broker
```
$ brew uninstall emqx
```

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

Run a single container

Get docker image

From Docker Hub
```
$ docker pull emqx/emqx:v4.0.0
```

Download the Docker image from emqx.io or Github 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

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

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: ${IMAGE}
    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

Start docker-compose cluster
```
$ docker-compose -p my_emqx up -d
```

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 or Github

Install and cluster via Helm (K8S、K3S)

Add helm repository

$ helm repo add emqx https://repos.emqx.io/charts
$ helm repo update

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

Start EMQ X Broker cluster

$ helm install my-emqx emqx/emqx

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

Get the source code

bash

$ git clone -b v4.0.0 https://github.com/emqx/emqx-rel.git

Set environment variables

bash

$ export EMQX_DEPS_DEFAULT_VSN=v4.0.0

Compile

bash

$ cd emqx-rel && make

Start EMQ X Broker

bash

$ cd _build/emqx-rel/_rel/emqx

$ ./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

Installation ​

One-click installation of shell script (Linux) ​

Package manager installation (Linux) ​

Centos ​

Ubuntu、Debian ​

OpenSUSE ​

Binary package installation (Linux) ​

ZIP (Linux、MaxOS、Windows) ​

Install via Homebrew(MacOS) ​

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

Run a single container ​

create a simple static cluster by docker-compose ​

Install and cluster via Helm (K8S、K3S) ​

Source code compilation and installation ​

Installation

One-click installation of shell script (Linux)

Package manager installation (Linux)

Centos

Ubuntu、Debian

OpenSUSE

Binary package installation (Linux)

ZIP (Linux、MaxOS、Windows)

Install via Homebrew(MacOS)

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

Run a single container

create a simple static cluster by docker-compose

Install and cluster via Helm (K8S、K3S)

Source code compilation and installation