MQTT server setup: EMQ X installation guide and FAQ

EMQ X is an open source IoT MQTT message server developed based on the Erlang/OTP platform. It is currently widely used in the construction of IoT platforms in various industries around the world. Its design goal is to achieve a highly reliable MQTT connection that carries a large number of Internet of Things terminals, and supports low-latency message routing among a large number of Internet of Things devices.

This article will take EMQ X v4.3.10 (open source version) as an example to introduce the installation method and common problems of EMQ X on Docker, Kubernetes, Windows and Linux, and provide help for everyone to use MQTT message server to quickly build an IoT platform.

Check before installation

In most cases, the environment of the operating system depends on the environment and the listening port will not cause problems. You can directly install and start in the test environment. EMQ X will check for possible problems and stop the startup and report an error.

However, we still recommend that when there are environmental changes such as upgrading EMQ X version and upgrading other services in the production environment, test and check before restarting EMQ X to avoid unnecessary losses.

Check environment dependencies

Common problems caused by environmental dependence are as follows:

• The OpenSSL version is incorrect: it is common on CentOS systems, and the OpenSSL version needs to be updated
• Missing MSVCRxxx.dll file: unique to Windows system, need to install the corresponding dependency library
• The installation package does not match the operating system: EMQ X needs to download the corresponding operating system and version, otherwise it will fail to start and error cannot execute binary file

For more problems and solutions, please refer to: EMQ X-Common Error

Check port occupancy

Port occupancy will cause EMQ X to fail to start or some functions are abnormal. Common symptoms are:

• When emqx start is executed, the startup timeout is prompted
• Cannot open Dashboard or keep reporting 404 Not Found error after opening

In the above situation, you can use the emqx console command to start EMQ X, and the detailed error log can be printed in the console mode.

EMQ X listens on the following ports by default:

port	Description
Cluster communication
4369-4380	Cluster communication
5370-5380	Cluster RPC communication
protocol access
1883	MQTT protocol port
11883	MQTT protocol port
8883	MQTT/SSL port
8083	MQTT/WebSocket port
5683	LwM2M port
Management monitoring
8081	HTTP API port
18083	Dashboard management console port

Install EMQ X using Docker

Using Docker does not need to establish an installation and operating environment, and you can install and start EMQ X faster. For the Docker installation tutorial, please refer to Install Docker Engine .

Run a single EMQ X node

After the Docker installation is complete, you can obtain the EMQ X image Docker Hub

docker pull emqx/emqx:4.3.10

Start the Docker container and establish port mapping:

docker run -d --name emqx \
  -p 1883:1883 \
  -p 8081:8081 \
  -p 8083:8083 \
  -p 8084:8084 \
  -p 8883:8883 \
  -p 18083:18083 \
emqx/emqx:4.3.10

After the startup is successful, visit the Dashboard management console http://localhost:18083 .

docker-compose simple cluster

Through docker-compose, you can quickly create an EMQ X cluster locally.

Create docker-compose.yaml file:

version: '3'

services:
    emqx1:
    image: emqx/emqx
    environment:
    - "EMQX_NAME=emqx"
    - "EMQX_HOST=node1.emqx.io"
    - "EMQX_CLUSTER__DISCOVERY=static"
    - "EMQX_CLUSTER__STATIC__SEEDS=[e-mail], [e-mail]"
    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
    environment:
    - "EMQX_NAME=emqx"
    - "EMQX_HOST=node2.emqx.io"
    - "EMQX_CLUSTER__DISCOVERY=static"
    - "EMQX_CLUSTER__STATIC__SEEDS=[e-mail], [e-mail]"
    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

Start the docker-compose cluster:

docker-compose -p my_emqx up -d

View the cluster:

docker exec -it my_emqx_emqx1_1 sh -c "emqx_ctl cluster status"
Cluster status: #{running_nodes => ['[e-mail]','[e-mail]'],
                    stopped_nodes => []}

Install EMQ X on Kubernetes

EMQ X Kubernetes Operator is a method for encapsulating, deploying and managing EMQ X launched by EMQ. It is also a specific application controller that allows DevOps personnel to orchestrate EMQ X clusters on Kubernetes and manage their life cycle.

EMQ X Kubernetes Operator can help users quickly create and manage EMQ X clusters in the Kubernetes environment, which not only greatly simplifies the deployment and management process, but also reduces the professional skills requirements for management and configuration.

It will make deployment and management work a low-cost, standardized, and repeatable ability to efficiently achieve cluster expansion, seamless upgrades, fault handling and unified monitoring.

For detailed deployment and usage, please see: https://github.com/emqx/emqx-operator .

Install EMQ X on Windows

Linux server is recommended for production deployment of EMQ X. Windows server is not recommended. Windows version is not provided in EMQ X Enterprise Edition. If you need to test, you can use Docker or virtual machine to install.

Download the ZIP package of the EMQ X version to be installed through the EMQ X download page , after decompressing the installation package, use the command line to enter the decompression directory and run:

cd D:\emqx

.\bin\emqx start

Install EMQ X on Linux

Linux one-click installation

EMQ X provides a one-click installation script for installation, the script will automatically identify and download the installation package of the corresponding operating system for installation:

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

Linux binary package installation

Download the ZIP package of the EMQ X version to be installed through the EMQ X download page , after decompressing the package, use the command line to enter the decompression directory and run:

cd /opt/emqx
./bin/emqx start

Yum package management tool installation

Install the required dependencies

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

Use the following command to set up a stable repository, taking CentOS 7 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

Other package management tools and operating system installation

Visit EMQ X installation document view more installation tutorials.

Deployment instructions

EMQ X supports different deployment methods. You can use EMQ X through cloud services or private deployment.

EMQ provides a fully managed cloud-native MQTT messaging service EMQ X Cloud: automated, fully managed deployment, without the need to manage server infrastructure, can bring easy and convenient MQTT cloud services to your IoT applications.

If you need private deployment, EMQ X also provides an enterprise version, which supports running anywhere in physical machines, containers/K8s, private clouds, hybrid clouds, and public clouds (such as Alibaba Cloud, Huawei Cloud and AWS), regardless of location Restricted and not locked by the manufacturer.

Both EMQ X Cloud and EMQ X Enterprise Edition provide free trial services and trial versions. You can complete the deployment within a few minutes and immediately start exploring and testing more abundant product features.

The following are the main differences between different versions. You can choose different deployment methods according to your own situation.