# Getting Started

Starting from download and installation, this document guides you through quickly getting an EMQX node up and running.

# Select EMQX Edition

EMQX as a software is released in different editions.

EMQ as a company offers a fully managed MQTT cloud service EMQX Cloud (opens new window) which runs EMQX Enterprise edition. You can customize the deployment to perfectly suit your business development plans and get started quickly.

# Install EMQX

# EMQX Cloud -- Service hosted by EMQ

EMQX Cloud is the first fully managed MQTT 5.0 public cloud service in the world. With the support of EMQX Cloud you can create an EMQX cluster in the cloud and use all the features of EMQX Enterprise.

This allows you to spend more time on business connections and less time on EMQX operation, maintenance, and management.

# Running EMQX in containers

Learn more about the docker image on Docker Hub (opens new window). Container deployment is the quickest way to start experimenting with EMQX.

Start Docker container:

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

For more information about Docker installation and building a cluster quickly with Docker Compose, please refer to Running with Docker (including a simple docker-compose cluster).

# Running EMQX in Kubernetes

For Kubernetes, EMQ offers EMQX Kubernetes Operator (opens new window).

EMQX Kubernetes Operator is an application orchestration tool based on Kubernetes native API, which is used for automatic deployment and life cycle management of EMQX clusters.

You can refer to the documentation (opens new window) to learn how to deploy EMQX using the Operator.

# Deploy EMQX with Terraform

Deploy all infrastructure including EMQX Enterprise clusters on the mainstream public cloud with one click through Terraform.

The fastest way to deploy EMQX Enterprise clusters on the public cloud.

For more information about Terraform installation and deployment, please refer to EMQX Terraform (opens new window)

# Run in a VM or on bare metal

EMQX can be deployed directly to bare metal servers or virtual machines. A minimum of 2 cores and 4GB RAM can run an EMQX installation.

EMQX has prebuilt packages downloadable for Linux (RedHat, CentOS, RockyLinux) as well as Debian, Ubuntu, and MacOS.

For other platforms which are not in the prebuilt list, you may build the executables from source code or simply contact EMQ (opens new window) for support.

# Start EMQX

After the installation, you can start EMQX through the command of systemctl or emqx. For more startup methods and precautions, keep reading below.

After EMQX is started successfully, you can visit http://localhost:18083/ (opens new window) (replace localhost with your actual IP address) through a browser to access EMQX Dashboard management console for device connection and related indicator monitoring and management.

# Start EMQX in the background

Below command starts EMQX in background (daemon mode)

emqx start

After the startup is successful, you can use the emqx ping command to check the running status of the node. If pong is returned, it means the running status is OK:

emqx ping

# Start EMQX using systemctl

sudo systemctl start emqx

Check if the service is working properly:

sudo systemctl status emqx

# Start EMQX using tar.gz package

Switch to the directory where EMQX was unzipped and execute the following command to start EMQX:

./bin/emqx start

In development mode, you can use the console command to start EMQX on the console and view the startup and runtime logs printed to the console.

./bin/emqx console

# Quick verification using an MQTT client

After startup, you can quickly verify if EMQX is working with any MQTT client. You can use the following client tools or client libraries to access EMQX

# Dashboard WebSocket tool

EMQX dashboard comes with a built-in WebSocket based MQTT client.

Visit the dashboard URL in a web browser and enter the page of Diagnose -> WebSocket Client, where you can use the MQTT over WebSocket client to quickly access EMQX.

The WebSocket page provides you with a simple but effective WebSocket client tool, which can be used for publishing, subscribing, and inspecting the messages.

# MQTTX desktop client tool

MQTTX is an elegant cross-platform MQTT 5.0 open source desktop client tool that supports running on macOS, Linux, and Windows.

MQTTX has many features. It provides a concise graphical interface with intuitive operational functionality. It supports MQTT/MQTT over WebSocket access with one-way/two-way SSL authentication, and supports Payload format conversion, simulation of test data with a custom scripts, automatic subscription of $SYS topic, viewing Traffic statistics, and more.

For download and use, please refer to the MQTT X website (opens new window).


# EMQX client library

For developers, we have compiled a list of popular MQTT clients for your reference.

# MQTT Client libraries

# Client example code

For MQTT client library example code, we try to cover as many mainstream programming languages and platforms as possible, see MQTT-Client-Examples (opens new window).

# Advanced operation

After completing the installation, startup, and access test, you can now continue to read the following documents for a proper in-production setup.

# Access Control

Authentication is an important part of most applications, and enabling authentication can effectively prevent malicious client connections.

Authorization rules, or Access Control List (ACL) can be configured to ensure only legitimate clients are permitted to publish or subscribe to certain topics.

  • Authentication Introduction: Select a backend to integrate with internal or external database, JWT or HTTP service as the authentication data source.
  • Authorization / ACL: Select a backend to integrate with internal or external database, or HTTP service as the ACL data source.

# Data Integration

Data integration is the data processing and distribution component of EMQX based on the publish-subscribe model. Data integration can easily integrate IoT data with Kafka, RDS, various SQL / NoSQL / time-series databases, and enterprise systems such as Oracle and SAP.

# Management Interfaces

Manage clusters via Web and CLI, REST API.

# Operation, maintenance and deployment

For official usage guidelines and best practices please read the following guides.