Install Docker

Step 1.1 - Update system

sudo apt update

Step 1.2 - Install Docker & Compose

sudo apt install -y docker.io docker-compose

Step 1.3 - Allow non-root Docker usage

sudo usermod -aG docker $USER
newgrp docker

Step 1.4 - Verify Docker

docker --version
docker-compose --version

Create EMQX project folder

Step 2.1 - Create folder

mkdir emqx-demo
cd emqx-demo

Step 2.2 - Create data folders

mkdir data log

Create docker-compose.yml

Step 3.1 - Open editor

nano docker-compose.yml

Step 3.2 - Paste this exactly

version: '3.8'

services:
  emqx:
    image: emqx/emqx:latest
    container_name: emqx
    ports:
      - "1883:1883"     # MQTT
      - "18083:18083"   # Dashboard
    environment:
      EMQX_ALLOW_ANONYMOUS: "false"
      EMQX_DASHBOARD__DEFAULT_USERNAME: admin
      EMQX_DASHBOARD__DEFAULT_PASSWORD: admin
    volumes:
      - ./data:/opt/emqx/data
      - ./log:/opt/emqx/log
    restart: unless-stopped

Save and exit (CTRL+O, Enter, CTRL+X).

Start EMQX

Step 4.1 - Pull & run

docker-compose pull
docker-compose up -d

Step 4.2 - Confirm it’s running

docker ps

Access EMQX Dashboard

Step 5.1 - Open browser

Go to

http://localhost:18083

Step 5.2 - Login

Username: admin
Password: admin

Create Built-in Database auth

Step 6.1 - Click Create and chose:

Mechanism: Password-Based
Backend: Built-in Database

Add User

Step 7.1 - Click Users then Add

Step 7.2 - Creat user name and password of the users

Username: testuser
Password: testpass

Enable Authorization (ACL / permissions)

Authentication = who are you Authorization = what are you allowed to do

Step 8.1 - Open Authorization page

Step 8.2 - Create authorization source

Click Create

Backend: Built-in Database

Step 8.3 - Add permission for Username

Install Mosquitto clients

Step 9.1 - Install Mosquitto

sudo apt update
sudo apt install -y mosquitto-clients
sudo snap install mosquitto

Testing

Step 10.1 - Terminal 1 Subscribe

mosquitto_sub -h <broker_ip> -u testuser -P testpass -I amebaClient -t outTopic

or

mosquitto_sub -h localhost -u testuser -P testpass -I amebaClient -t outTopic

Step 10.1 - Terminal 2 Publish allowed

mosquitto_pub -h localhost -u testuser -P testpass -I amebaClient -t outTopic -m "hello world"

Testing with MQTT explore

Install program from MQTT Explore

Setup BASIC setting:

Setup ADVANCED setting:

Connect, then chose the topic and PUBLISH

Clean restart

Stop & remove old container

docker-compose down

sudo snap stop mosquitto

If you ran EMQX before with volumes and want a true reset:

rm -rf data log
mkdir data log

Find your PC’s local IP

ip addr show