Get Started

EMQX is the world’s most scalable and reliable MQTT messaging platform that can help you to connect, move and process your business data reliably in real-time. With this all-in-one MQTT platform, you can easily build your Internet of Things (IoT) applications with significant business impacts.

This chapter gives you a tour of how to download and install EMQX and how to test the connecting and messaging services with our built-in WebSocket tool.

TIP

Besides the deployment methods introduced in this quickstart guide, 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 you can start your MQTT services and connect your IoT devices to any cloud with zero need for infrastructure maintenance.

Select Your EMQX Edition

EMQX is available in Open Source and Enterprise editions, you may click the link below to download the edition as your business needs.

• Open source edition (opens new window)
• Enterprise edition (opens new window)

The world's most scalable distributed MQTT broker with a high-performance real-time message processing engine, powering event streaming for IoT devices at a massive scale.

• Fully open-sourced under APL 2.0
• Support MQTT 3.1.0, MQTT 3.1.1 and MQTT 5.0, support MQTT-SN
• Highly available, masterless clustering
• High concurrency with low latency
• Extensible gateways and plugins
• Data integration by calling HTTP APIs

Download (opens new window)

The world’s leading Cloud-Native IoT Messaging Platform with an all-in-one distributed MQTT broker and SQL-based IoT rule engine. It combines high performance with reliable data transport, processing, and integration for business-critical IoT solutions.

• Support for multiple IoT protocols
• Powerful SQL-based data integrations
• Rich data persistence and bridging choices
• Management & monitoring center
• Global technical support team

Try Free (opens new window)

Install EMQX

EMQX can be run with Docker, installed with EMQX Kubernetes Operator (opens new window), or installed on a computer or virtual machine (VM) via a download package. If you choose to install EMQX with a download package, the following operating systems are currently supported:

• RedHat
• CentOS
• RockyLinux
• AmazonLinux
• Ubuntu
• Debian
• macOS
• Linux
• Windows

For other platforms not listed above, you can try to build and install with source code or simply contact EMQ (opens new window) for support. {% endemqxce %}

In addition, you can also deploy EMQX with one-click through EMQX Terraform (opens new window) on the cloud, for example, Alibaba Cloud (opens new window) and AWS (opens new window).

Install EMQX With Docker/Installation Package

In this quick start guide, we will show you the easiest ways to start or run EMQX, that is, with Docker or with the installation package.

Container deployment is the quickest way to start exploring EMQX. In this section, we will show you how to run EMQX with Docker.

1. To download and start the latest version of EMQX, enter the command below.

   Ensure Docker (opens new window) is installed and running before you execute this command.

   docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 8084:8084 -p 8883:8883 -p 18083:18083 emqx/emqx:latest
   

2. Start your web browser and enter http://localhost:18083/ ( localhost can be substituted with your IP address) in the address bar to access the EMQX Dashboard, from where you can connect to your clients or check the running status.

   Default user name and password:

   admin

   public

You can also install EMQX with zip/tar.gz files on a computer or VM, so you can easily adjust the configurations or run performance tuning. In this section, we will use macOS (opens new window) (macOS11 amd64) as an example to illustrate the operating steps.

Note: Considering all the runtime dependencies, it is recommended to use zip/tar.gz files for testing and hot upgrades, and NOT recommended in a production environment.

1. To download the zip file, enter:

   wget https://www.emqx.com/en/downloads/broker/5.0.26/emqx-5.0.26-macos11-amd64.zip
   

2. To install EMQX, enter:

   mkdir -p emqx && unzip emqx-5.0.26-macos11-amd64.zip -d emqx
   

3. To run EMQX, enter:

   ./emqx/bin/emqx start
   

4. Start your web browser and enter http://localhost:18083/ ( localhost can be substituted with your IP address) in the address bar to access the EMQX Dashboard, from where you can connect to your clients or check the running status.

   The default user name and password are admin & public. You will be prompted to change the default password once logged in.

5. To stop EMQX, enter:

   ./emqx/bin/emqx stop
   

To uninstall EMQX after your testing, you only need to delete the EMQX folders.

:::

::::

Use MQTTX to Verify Connection

Now that you have successfully started EMQX, you can continue to test the connection and message services with MQTT X

MQTT X (opens new window) is an elegant cross-platform MQTT 5.0 desktop client, running on macOS, Linux, and Windows. By utilizing a chat style of user interface, MQTT X allows users to quickly create connections and save multiple clients, which facilitates users to quickly test the MQTT/MQTTS connection, as well as the subscription and publication of MQTT messages.

This section will introduce how to verify the connection with MQTT X Web (opens new window), the browser-based MQTT 5.0 WebSocket client tool, with zero need to download or install any application.

Prerequisites

The broker address and the port information should be prepared before testing the connection:

• Broker address: The IP address of your server, in general.
• Port: Click Management -> Listeners on the left navigation menu to get the port number.

1. Click MQTT X Web (opens new window) to visit the browser-based MQTT X.

2. Configure and establish the MQTT connection. Click the + New Connection button to enter the configure page:

   • Name: Input a connection name, for example, MQTTX_Test;

   • Host

     • Select the protocol type via the drop-down list, for example, select ws:// if the WebSockets protocol is adopted; MQTT X Web only supports Websockets protocol, to test the SSL/TLS connection, download MQTT X desktop client (opens new window);
     • Fill in the EMQX address, for example, emqx@127.0.0.1;

   • Port: for example, 8083 for the WebSockets protocol;

     Keep the default setting for the other fields or set it as your business needs. For a detailed explanation of different fields, see MQTT User Manual - Connect (opens new window).

   Then click the Connect button at the top right corner of the page.

3. Subscribe to topics. After the connection is successfully established, you can continue to subscribe to different topics. Click + New Subscription. MQTT X Web has already filled in some fields, according to the setting, you will subscribe to topic testtopic/# with QoS level of 0. You can repeat this step to subscribe to different topics, and MQTT X Web will differentiate topics with colors.

4. Test the publish/receive of messages: Click the send icon in the bottom right corner of the chat area, then the messages successfully sent will appear in the chat window above.

If you'd like to continue the testing, such as one-way/two-way SSL authentication and simulate test data with customized scripts, you can continue to explore with MQTT X (opens new window).

Then you can click Dashboard in the left navigation tree to return to the Dashboard page and check metrics such as Connections, Topics, Subscriptions, Incoming Messages, Outgoing messages, and Dropped Messages.

Advanced Operation

So far, you have completed the installation, startup, and access test of EMQX, you can continue to try out more advanced capabilities of EMQX, such as authentication and authorization and integration with Rule Engine.

Contact Us

If you have any questions on the use of EMQX or EMQ products, you are warmly welcome to contact us (opens new window) for professional support.