Installation EMQX
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.
Installation Environment
The Erlang VM powering EMQX relies on system locale settings to enable Unicode support for various functionalities, including filenames and terminal IO 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:
Download
EMQX releases the installation packages for different operating systems or platforms in each release. You may click the links below to download.
- EMQX website: https://www.emqx.io/downloads
You can also download the alpha, beta, or rc versions from our GitHub pages. {% endemqxce %}
TIP
Besides the above deployment methods, you are also welcome to try our EMQX Cloud, a fully managed MQTT service for IoT. You only need to register for an account 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 |
|---|---|---|---|
| Ubuntu | Ubuntu 18.04 Ubuntu 20.04 Ubuntu 22.04 | Yes | Yes |
| Debian | Debian 10 Debian 11 Debian 12 | Yes | Yes |
| CentOS/RHEL | CentOS 7 Rocky Linux 8 Rocky Linux 9 | Yes | Yes |
| Amazon Linux | Amazon Linux 2 Amazon Linux 2023 | Yes | Yes |
| macOS | macOS 11 macOS 12 macOS 13 (Homebrew) | Yes | Yes |
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 |
|---|---|---|
| Node | 1 | 2 |
| CPU | 1 core | 16 core |
| Memory | 512 MB | 32 GB |
| Disk space | 1 GB | 50 GB |
TIP
In production environments, you can use the Server Estimate 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 |
|---|---|---|---|
etc | Static config files | ./etc | /etc/emqx |
data | Database and config | ./data | /var/lib/emqx |
log | Log files | ./log | /var/log/emqx |
releases | Boot instructions | ./releases | /usr/lib/emqx/releases |
bin | Executables | ./bin | /usr/lib/emqx/bin |
lib | Erlang code | ./lib | /usr/lib/emqx/lib |
erts-* | Erlang runtime | ./erts-* | /usr/lib/emqx/erts-* |
plugins | Plugins | ./plugins | /usr/lib/emqx/plugins |
TIP
- 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
/opt/emqxdirectory. - The
data,log, andpluginsdirectories are configurable via the configuration files. Mounting thedatadirectory to a high-performance disk is recommended for better performance. For nodes belonging to the same cluster, the configuration for thedatadirectory should be the same. For more information about clusters, see Cluster.
The table below introduces the files and subfolders of some directories.
| Directory | Description | Permissions | Files |
|---|---|---|---|
| bin | Executables | Read | emqx and emqx.cmd: Executables of EMQX. For details, see Command Line Interface. |
| etc | Configuration files | Read | emqx.conf: Main configuration file for EMQX, contains all the commonly-used configuration items.emqx-example-en.conf: Demo configuration files of EMQX, contains all the configurable items.acl.conf: Default ACl rules.vm.args: Operating parameters of the Erlang virtual machine.certs/: X.509 keys and certificate files for EMQX SSL listeners, may also be used in the SSL/TLS connection when integrating with external systems. |
| data | Operating data | Write | authz: Stores file authorization rules uploaded by REST API or Dashboard. For details, see Authorization - File. certs: Stores certificate files uploaded by REST API or Dashboard.configs: Stores configuration files generated at boot, or configuration overrides by changes from API or CLI.mnesia: Built-in database to store EMQX operating data, including alarm records, authentication and authorization data of the clients, Dashboard user information, etc. If the directory is deleted, all these operating data will be lost.— May contain subdirectories named after different node, e.g., emqx@127.0.0.1. Note: In case of node renaming, you should also delete or remove the corresponding subdirectory. — Can use command emqx ctl mnesia to query the built-in database. For details, see Management Command CLI.patches: Stores the .beam files for EMQX to load as a hot patch. Can be used for a quick fix.trace: Online tracing log files.In production, it is recommended to periodically backup the data directory (excluding the trace folder ) for data safety. |
| log | Operating logs | Read | emqx.log.*: Operation logs of EMQX, for more information, see logs. |
TIP
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.
etc/emqx.confdata/configs/cluster.hocon
EMQX reads the configuration items from these files and converts them to the Erlang native configuration file format, to apply the configurations at runtime.