This chapter walks you through the basic installation steps for EMQX, the minimum hardware specification, and the file and directory locations to facilitate future configuration and maintenance jobs.
This chapter will also cover how to configure a license for EMQX and how to migrate from EMQX 4.x to EMQX 5.1.0.
# Installation Environment
The Erlang VM powering EMQX relies on system locale settings to enable Unicode support for various functionalities, including filenames (opens new window) and terminal IO (opens new window) in interactive Erlang shells.
If you use the Linux operating system, it is recommended to make sure that UTF-8 locale is enabled in the system environment before starting EMQX. Click the tabs to see how to enable the UTF-8 locale on different platforms:
EMQX releases the corresponding Docker image and the installation packages for different operating systems or platforms in each release. You may click the link below to download.
Besides the above deployment methods, you are also welcome to try our EMQX Cloud (opens new window), a fully managed MQTT service for IoT. You only need to register for an account (opens new window) before starting your MQTT services and connecting your IoT devices to any cloud with zero need for infrastructure maintenance.
# Supported Operating Systems
The table below lists the operating systems and versions that EMQX supports.
|Operating system||Versions supported||x86_64/amd64||arm64|
# Hardware Specification
Depending on the number of client connections, message rate, message size, and enabled features, the minimum hardware specification for EMQX varies.
Below are hardware specifications for running EMQX with simple workloads, supporting 100,000 client connections and 100,000 messages per second of throughput.
|Item||Minimum configuration||Recommended configuration|
|CPU||1 core||16 core|
|Memory||512 MB||32 GB|
|Disk space||1 GB||50 GB|
In production environments, you can use the Server Estimate (opens new window) calculator to calculate the recommended hardware specification under various maximum connections and message throughput.
# Files and Directories
After installation, EMQX creates some directories to store running and configuration files, data, and logs. The table below lists the directories created and their file path under different installation methods:
|Directory||Description||Installed with tar.gz||Installed with RPM/DEB|
|Database and files|
- When installed with the compressed package, the directory is relative to the directory where the software is installed.
- When installed with Docker container, EMQX is installed in the
pluginsdirectories are configurable via the configuration files. Mounting the
datadirectory to a high-performance disk is recommended for better performance. For nodes belonging to the same cluster, the configuration for the
datadirectory should be the same. For more information about clusters, see Cluster.
The table below introduces the files and subfolders of some directories.
— May contain subdirectories named after different node, e.g.,
— Can use command
In production, it is recommended to periodically backup the
EMQX stores the configuration information in the
data/configs and the
etc directory. The
etc directory stores read-only configuration files, while configuration updates from the Dashboard or REST API are saved in the
data/configs directory to support hot configuration reloads at runtime.
EMQX reads the configuration items from these files and converts them to the Erlang native configuration file format, to apply the configurations at runtime.