EMQX Open Source MQTT Broker

edge

Open-source MQTT broker for IoT, IIoT, and connected vehicles - Single Broker deployment

Image details

Pulls: 5.0M

Architectures: amd64, arm64, arm64/v8

Image size: 103 MB

Latest: 5.8.8

User: library

Created: Apr 07, 2022

Updated: 6 days ago

Status: active

Configuration

Type

Compose

Platform

linux

Image

emqx:5.5.0

Ports

1883:18838083:80838084:80848883:888318083:18083

Volumes

/opt/emqx/data : emqx_data/opt/emqx/log : emqx_log

Env vars

EMQX_DASHBOARD__DEFAULT_USERNAME=${EMQX_DASHBOARD__DEFAULT_USERNAME}EMQX_DASHBOARD__DEFAULT_PASSWORD=${EMQX_DASHBOARD__DEFAULT_PASSWORD}

Restart

unless-stopped

Source

Repo

Template by portainer·Source

Installation

Ensure both Docker and Portainer are installed, and up-to-date
Log into your Portainer web UI
Under Settings → App Templates, paste the below URL
Head to Home → App Templates, and the list of apps will show up
Select the app you wish to deploy, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json

Show Me

docker run -d --name emqx \
  -p 1883:1883 \
  -p 8083:8083 \
  -p 8084:8084 \
  -p 8883:8883 \
  -p 18083:18083 \
  -e 'EMQX_DASHBOARD__DEFAULT_USERNAME=${EMQX_DASHBOARD__DEFAULT_USERNAME}' \
  -e 'EMQX_DASHBOARD__DEFAULT_PASSWORD=${EMQX_DASHBOARD__DEFAULT_PASSWORD}' \
  -v emqx_data:/opt/emqx/data \
  -v emqx_log:/opt/emqx/log \
  --restart=unless-stopped \
  emqx:5.5.0

If the stack expects env vars, set them or add them to a .env file first.

version: '3'

services:
  emqx:
    image: emqx:5.5.0
    container_name: emqx
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "/opt/emqx/bin/emqx", "ctl", "status"]
      interval: 5s
      timeout: 25s
      retries: 5
    networks:
      emqx_bridge:
    environment:
      - EMQX_DASHBOARD__DEFAULT_USERNAME=${EMQX_DASHBOARD__DEFAULT_USERNAME}
      - EMQX_DASHBOARD__DEFAULT_PASSWORD=${EMQX_DASHBOARD__DEFAULT_PASSWORD}
    ports:
      - 1883:1883
      - 8083:8083
      - 8084:8084
      - 8883:8883
      - 18083:18083 
    volumes:
      - emqx_data:/opt/emqx/data
      - emqx_log:/opt/emqx/log

networks:
  emqx_bridge:
 
volumes:
  emqx_data:
  emqx_log:

Or, use the original compose file, straight from the template repo. Deploy with:

git clone https://github.com/portainer/templates
cd templates
docker compose -f edge/emqx/docker-compose.yml up -d

Save this file as emqx-open-source-mqtt-broker-stack.yml, then from a manager node, run docker stack deploy -c emqx-open-source-mqtt-broker-stack.yml emqx-open-source-mqtt-broker

version: '3.8'
services:
  emqx-open-source-mqtt-broker:
    image: emqx:5.5.0
    ports:
      - '1883:1883'
      - '8083:8083'
      - '8084:8084'
      - '8883:8883'
      - '18083:18083'
    volumes:
      - emqx_data:/opt/emqx/data
      - emqx_log:/opt/emqx/log
    environment:
      EMQX_DASHBOARD__DEFAULT_USERNAME: ${EMQX_DASHBOARD__DEFAULT_USERNAME}
      EMQX_DASHBOARD__DEFAULT_PASSWORD: ${EMQX_DASHBOARD__DEFAULT_PASSWORD}
    deploy:
      restart_policy:
        condition: any

Save each file below into a folder, then run kubectl apply -f .
Written for k3s, but works on any cluster: bind mounts use hostPath, named volumes get a persistent volume claim, and ports are exposed via a LoadBalancer service.

`emqx-open-source-mqtt-broker-deployment.yaml`

apiVersion: apps/v1
kind: Deployment
metadata:
  name: emqx-open-source-mqtt-broker
  labels:
    app: emqx-open-source-mqtt-broker
spec:
  replicas: 1
  selector:
    matchLabels:
      app: emqx-open-source-mqtt-broker
  template:
    metadata:
      labels:
        app: emqx-open-source-mqtt-broker
    spec:
      containers:
        - name: emqx-open-source-mqtt-broker
          image: emqx:5.5.0
          env:
            - name: EMQX_DASHBOARD__DEFAULT_USERNAME
              value: ${EMQX_DASHBOARD__DEFAULT_USERNAME}
            - name: EMQX_DASHBOARD__DEFAULT_PASSWORD
              value: ${EMQX_DASHBOARD__DEFAULT_PASSWORD}
          ports:
            - containerPort: 1883
              protocol: TCP
            - containerPort: 8083
              protocol: TCP
            - containerPort: 8084
              protocol: TCP
            - containerPort: 8883
              protocol: TCP
            - containerPort: 18083
              protocol: TCP
          volumeMounts:
            - name: emqx-open-source-mqtt-broker-data-0
              mountPath: /opt/emqx/data
            - name: emqx-open-source-mqtt-broker-data-1
              mountPath: /opt/emqx/log
      volumes:
        - name: emqx-open-source-mqtt-broker-data-0
          hostPath:
            path: emqx_data
        - name: emqx-open-source-mqtt-broker-data-1
          hostPath:
            path: emqx_log

`emqx-open-source-mqtt-broker-service.yaml`

apiVersion: v1
kind: Service
metadata:
  name: emqx-open-source-mqtt-broker
spec:
  type: LoadBalancer
  selector:
    app: emqx-open-source-mqtt-broker
  ports:
    - name: 1883-tcp
      port: 1883
      targetPort: 1883
      protocol: TCP
    - name: 8083-tcp
      port: 8083
      targetPort: 8083
      protocol: TCP
    - name: 8084-tcp
      port: 8084
      targetPort: 8084
      protocol: TCP
    - name: 8883-tcp
      port: 8883
      targetPort: 8883
      protocol: TCP
    - name: 18083-tcp
      port: 18083
      targetPort: 18083
      protocol: TCP

Save this file as ~/.config/containers/systemd/emqx-open-source-mqtt-broker.container

[Unit]
Description=EMQX Open Source MQTT Broker

[Container]
Image=emqx:5.5.0
ContainerName=emqx-open-source-mqtt-broker
PublishPort=1883:1883
PublishPort=8083:8083
PublishPort=8084:8084
PublishPort=8883:8883
PublishPort=18083:18083
Environment=EMQX_DASHBOARD__DEFAULT_USERNAME=${EMQX_DASHBOARD__DEFAULT_USERNAME}
Environment=EMQX_DASHBOARD__DEFAULT_PASSWORD=${EMQX_DASHBOARD__DEFAULT_PASSWORD}
Volume=emqx_data:/opt/emqx/data
Volume=emqx_log:/opt/emqx/log

[Service]
Restart=always

[Install]
WantedBy=default.target

Then reload systemd and start the service:

systemctl --user daemon-reload
systemctl --user start emqx-open-source-mqtt-broker

For a system-wide service, use /etc/containers/systemd/ and drop --user.

For more installation options, see the Documentation in our GitHub repo

DEPRECATION NOTICE

Starting from v5.9.0, EMQX has unified all features from the previous Open Source and Enterprise editions into a single, powerful offering with the Business Source License (BSL) 1.1.
If you want to understand why we made the change, please read this blog post, and if you want to know more about the new license, please read the EMQX Licensing FAQ.
Consequently, we stopped publishing the emqx Docker Official Image. EMQX v5.9.0+ will only be available in the emqx/emqx and emqx/emqx-enterprise Docker Hub repositories.

Quick reference

Maintained by:

[EMQ Technologies](https://github.com/emqx)

Where to get help:

[Discussions](https://github.com/emqx/emqx/discussions) or [Discord](https://discord.gg/xYGf3fQnES)

Supported tags and respective `Dockerfile` links

5.7.2, 5.7

5.8.8, 5.8, 5, latest

Quick reference (cont.)

Where to file issues:

[https://github.com/emqx/emqx-docker/issues](https://github.com/emqx/emqx-docker/issues?q=)

Supported architectures: (more info)

[`amd64`](https://hub.docker.com/r/amd64/emqx/), [`arm64v8`](https://hub.docker.com/r/arm64v8/emqx/)

Published image artifact details:

[repo-info repo's `repos/emqx/` directory](https://github.com/docker-library/repo-info/blob/master/repos/emqx) ([history](https://github.com/docker-library/repo-info/commits/master/repos/emqx))  
(image metadata, transfer size, etc)

Image updates:

[official-images repo's `library/emqx` label](https://github.com/docker-library/official-images/issues?q=label%3Alibrary%2Femqx)  
[official-images repo's `library/emqx` file](https://github.com/docker-library/official-images/blob/master/library/emqx) ([history](https://github.com/docker-library/official-images/commits/master/library/emqx))

Source of this description:

[docs repo's `emqx/` directory](https://github.com/docker-library/docs/tree/master/emqx) ([history](https://github.com/docker-library/docs/commits/master/emqx))

What is EMQX

EMQX is the world's most scalable open-source MQTT broker with a high performance that connects 100M+ IoT devices in 1 cluster, while maintaining 1M message per second throughput and sub-millisecond latency.
EMQX supports multiple open standard protocols like MQTT, HTTP, QUIC, and WebSocket. It's 100% compliant with MQTT 5.0 and 3.x standard, and secures bi-directional communication with MQTT over TLS/SSL and various authentication mechanisms.
With the built-in powerful SQL-based rules engine, EMQX can extract, filter, enrich and transform IoT data in real-time. In addition, it ensures high availability and horizontal scalability with a masterless distributed architecture, and provides ops-friendly user experience and great observability.
EMQX boasts more than 20K+ enterprise users across 50+ countries and regions, connecting 100M+ IoT devices worldwide, and is trusted by over 400 customers in mission-critical scenarios of IoT, IIoT, connected vehicles, and more, including over 70 Fortune 500 companies like HPE, VMware, Verifone, SAIC Volkswagen, and Ericsson.

How to use this image

Run EMQX

Execute some command under this docker image

$ docker run -d --name emqx emqx:${tag}

For example

$ docker run -d --name emqx -p 18083:18083 -p 1883:1883 emqx:latest

The EMQX broker runs as Linux user emqx in the docker container.

Configuration

All EMQX Configuration in etc/emqx.conf can be configured via environment variables.
Example:

EMQX_DASHBOARD__DEFAULT_PASSWORD       <--> dashboard.default_password
EMQX_NODE__COOKIE                      <--> node.cookie
EMQX_LISTENERS__SSL__default__ENABLE   <--> listeners.ssl.default.enable

Note: The lowercase use of 'default' is not a typo. It is used to demonstrate that lowercase environment variables are equivalent.

Prefix EMQX_ is removed
All upper case letters are replaced with lower case letters
__ is replaced with .

For example, set MQTT TCP port to 1883

$ docker run -d --name emqx -e EMQX_DASHBOARD__DEFAULT_PASSWORD=mysecret -p 18083:18083 -p 1883:1883 emqx:latest

Please read more about EMQX configuration in the official documentation

EMQX node name configuration

Environment variable EMQX_NODE__NAME allows you to specify an EMQX node name, which defaults to <container_name>@<container_ip>.
If not specified, EMQX determines its node name based on the running environment or other environment variables used for node discovery.

Cluster

EMQX supports a variety of clustering methods, see our documentation for details.
Let's create a static node list cluster from Docker Compose.

Create compose.yaml:

services:
  emqx1:
    image: emqx:latest
    environment:
    - "[email protected]"
    - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
    - "EMQX_CLUSTER__STATIC__SEEDS=[[email protected], [email protected]]"
    networks:
      emqx-bridge:
        aliases:
        - node1.emqx.io

  emqx2:
    image: emqx:latest
    environment:
    - "[email protected]"
    - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
    - "EMQX_CLUSTER__STATIC__SEEDS=[[email protected], [email protected]]"
    networks:
      emqx-bridge:
        aliases:
        - node2.emqx.io

networks:
  emqx-bridge:
    driver: bridge

Start the Docker Compose services

docker compose -p my_emqx up -d

View cluster

$ docker exec -it my_emqx_emqx1_1 sh -c "emqx ctl cluster status"
Cluster status: #{running_nodes => ['[email protected]','[email protected]'],
                  stopped_nodes => []}

Persistence

If you want to persist the EMQX docker container, you need to keep the following directories:

/opt/emqx/data
/opt/emqx/log

Since data in these folders are partially stored under the /opt/emqx/data/mnesia/${node_name}, the user also needs to reuse the same node name to see the previous state. To make this work, one needs to set the host part of EMQX_NODE__NAME to something static that does not change when you restart or recreate the container. It could be container name, hostname or loopback IP address 127.0.0.1 if you only have one node.
In if you use Docker Compose, the configuration would look something like this:

volumes:
  vol-emqx-data:
    name: foo-emqx-data
  vol-emqx-log:
    name: foo-emqx-log

services:
  emqx:
    image: emqx:latest
    restart: always
    environment:
      EMQX_NODE__NAME: [email protected]
    volumes:
      - vol-emqx-data:/opt/emqx/data
      - vol-emqx-log:/opt/emqx/log

Kernel Tuning

Under Linux host machine, the easiest way is Tuning guide.
If you want tune Linux kernel by docker, you must ensure your docker is latest version (>=1.12).

docker run -d --name emqx -p 18083:18083 -p 1883:1883 \
    --sysctl fs.file-max=2097152 \
    --sysctl fs.nr_open=2097152 \
    --sysctl net.core.somaxconn=32768 \
    --sysctl net.ipv4.tcp_max_syn_backlog=16384 \
    --sysctl net.core.netdev_max_backlog=16384 \
    --sysctl net.ipv4.ip_local_port_range=1000 65535 \
    --sysctl net.core.rmem_default=262144 \
    --sysctl net.core.wmem_default=262144 \
    --sysctl net.core.rmem_max=16777216 \
    --sysctl net.core.wmem_max=16777216 \
    --sysctl net.core.optmem_max=16777216 \
    --sysctl net.ipv4.tcp_rmem=1024 4096 16777216 \
    --sysctl net.ipv4.tcp_wmem=1024 4096 16777216 \
    --sysctl net.ipv4.tcp_max_tw_buckets=1048576 \
    --sysctl net.ipv4.tcp_fin_timeout=15 \
    emqx:latest

REMEMBER: DO NOT RUN EMQX DOCKER PRIVILEGED OR MOUNT SYSTEM PROC IN CONTAINER TO TUNE LINUX KERNEL, IT IS UNSAFE.

License

View license information for the software contained in this image.
As with all Docker images, these likely also contain other software which may be under other licenses (such as Bash, etc from the base distribution, along with any direct or indirect dependencies of the primary software being contained).
Some additional license information which was able to be auto-detected might be found in the repo-info repository's emqx/ directory.
As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies with any relevant licenses for all software contained within.

Serve EMQX Open Source MQTT Broker on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxy Domain App port Upstream

Proxying emqx-open-source-mqtt-broker.example.com to http://emqx:1883

Add this to your Caddyfile

emqx-open-source-mqtt-broker.example.com {
	reverse_proxy http://emqx:1883
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

In Portainer, go to Containers, click the container, then Logs. Or run docker logs <container>
Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:1883 failed: port is already allocated", something else on your server is using that port.

Find what's using it: sudo ss -tlnp | grep :1883
Stop the other service, or pick a different host port. In 1883:1883 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

Use your server's real IP: http://your-server-ip:1883. The 0.0.0.0 link Portainer shows isn't a real address.
Give it a minute after first deploy, emqx can take a while to initialise.
Make sure your firewall allows the port, e.g. sudo ufw allow 1883

Image won't pull

Test the pull directly on the host: docker pull emqx:5.5.0

"manifest unknown" means the tag no longer exists.
"toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
"no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

This image supports: amd64, arm64, arm64/v8
Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Container keeps restarting

The unless-stopped restart policy relaunches the app after every crash, so the real error can scroll past.

Check the logs right after a restart, the last few lines before it died are the useful ones.
Get the exit code with docker inspect <container> --format '{{.State.ExitCode}}'
Still stuck? Redeploy once with the restart policy set to no so the failure stays visible.

Stack won't deploy

Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.

YAML only accepts spaces for indentation, a single tab breaks the whole file.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

Bug within the app: Open an issue within emqx's repo
Template not working: Open an issue on portainer/templates
This website not working: Open an issue on lissy93/portainer-templates

Similar apps

Anyviz Cloud Adaptor edge CockroachDB (stack) edge

Floating License Server edge

Grafana Dashboard edge

Inductive Automation - Ignition Gateway edge

InfluxDB for Edge edge

Litmus Edge edge

Litmus Edge Digital Factory Demo edge

EMQX Open Source MQTT Broker

Image details

Configuration

Installation

Via Portainer

Template Import URL

Docker Run

Docker Compose

Docker Swarm

Kubernetes

emqx-open-source-mqtt-broker-deployment.yaml

emqx-open-source-mqtt-broker-service.yaml

Podman Quadlet

Alternative Methods

Container Documentation

DEPRECATION NOTICE

Quick reference

Supported tags and respective Dockerfile links

Quick reference (cont.)

What is EMQX

How to use this image

Run EMQX

Configuration

EMQX node name configuration

Cluster

Persistence

Kernel Tuning

License

Recent versions

Proxy configurator

Troubleshooting

Check the logs first

Port already in use

Running but the page won't load

Image won't pull

"exec format error"

Container keeps restarting

Stack won't deploy

Raise an issue

Similar apps

`emqx-open-source-mqtt-broker-deployment.yaml`

`emqx-open-source-mqtt-broker-service.yaml`

Supported tags and respective `Dockerfile` links