-
Where to get help:
https://emqx.io, https://github.com/emqx/emqx-rel, or https://github.com/emqx/emqx
-
Where to file issues:
-
Supported architectures
amd64
,arm64v8
,arm32v7
,i386
,s390x
-
Supported Docker versions:
EMQ X MQTT broker is a fully open source, highly scalable, highly available distributed MQTT messaging broker for IoT, M2M and Mobile applications that can handle tens of millions of concurrent clients.
Starting from 3.0 release, EMQ X broker fully supports MQTT V5.0 protocol specifications and backward compatible with MQTT V3.1 and V3.1.1, as well as other communication protocols such as MQTT-SN, CoAP, LwM2M, WebSocket and STOMP. The 3.0 release of the EMQ X broker can scaled to 10+ million concurrent MQTT connections on one cluster.
Execute some command under this docker image
docker run -d --name emqx emqx/emqx:$(tag)
For example
docker run -d --name emqx -p 18083:18083 -p 1883:1883 emqx/emqx:latest
The emqx broker runs as linux user emqx
in the docker container.
Use the environment variable to configure the EMQ X docker container.
The environment variables which with EMQX_
prefix are mapped to configuration file, .
get replaced by __
.
Example:
EMQX_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors
EMQX_MQTT__MAX_PACKET_SIZE <--> mqtt.max_packet_size
Also the environment variables which with PLATFORM_
prefix are mapped to template string in configuration file.
PLATFORM_ETC_DIR <--> {{ platform_etc_dir }}
Non mapped environment variables:
EMQX_NAME
EMQX_HOST
These environment variables will ignore for configuration file.
NOTE: All EMQ X Configuration in etc/emqx.conf could config by environment. The following list is just an example, not a complete configuration.
Options | Default | Mapped | Description |
---|---|---|---|
EMQX_NAME | container name | none | emqx node short name |
EMQX_HOST | container IP | none | emqx node host, IP or FQDN |
EMQX_WAIT_TIME | 5 | none | wait time in sec before timeout |
PLATFORM_ETC_DIR | /opt/emqx/etc | {{ platform_etc_dir }} | The etc directory |
PLATFORM_LOG_DIR | /opt/emqx/log | {{ platform_log_dir }} | The log directory |
EMQX_NODE__NAME | EMQX_NAME@EMQX_HOST | node.name | Erlang node name, name@ipaddress/host |
EMQX_NODE__COOKIE | emqx_dist_cookie | node.cookie | cookie for cluster |
EMQX_LOG__CONSOLE | console | log.console | log console output method |
EMQX_ALLOW_ANONYMOUS | true | allow_anonymous | allow mqtt anonymous login |
EMQX_LISTENER__TCP__EXTERNAL | 1883 | listener.tcp.external | MQTT TCP port |
EMQX_LISTENER__SSL__EXTERNAL | 8883 | listener.ssl.external | MQTT TCP TLS/SSL port |
EMQX_LISTENER__WS__EXTERNAL | 8083 | listener.ws.external | HTTP and WebSocket port |
EMQX_LISTENER__WSS__EXTERNAL | 8084 | listener.wss.external | HTTPS and WSS port |
EMQX_LISTENER__API__MGMT | 8080 | listener.api.mgmt | MGMT API port |
EMQX_MQTT__MAX_PACKET_SIZE | 64KB | mqtt.max_packet_size | Max Packet Size Allowed |
The list is incomplete and may changed with etc/emqx.conf and plugin configuration files. But the mapping rule is similar.
If set EMQX_NAME
and EMQX_HOST
, and unset EMQX_NODE__NAME
, EMQX_NODE__NAME=$EMQX_NAME@$EMQX_HOST
.
For example, set mqtt tcp port to 1883
docker run -d --name emqx -e EMQX_LISTENER__TCP__EXTERNAL=1883 -p 18083:18083 -p 1883:1883 emqx/emqx:latest
Oprtions | Default | Description |
---|---|---|
EMQX_LOADED_MODULES | see content below | default modules emqx loaded |
Default environment variable EMQX_LOADED_MODULES
, including
emqx_mod_acl_internal
emqx_mod_presence
# The default EMQX_LOADED_MODULES env
EMQX_LOADED_MODULES="emqx_mod_acl_internal,emqx_mod_acl_internal"
For example, set EMQX_LOADED_MODULES=emqx_mod_delayed,emqx_mod_rewrite
to load these two modules.
You can use comma, space or other separator that you want.
All the modules defined in env EMQX_LOADED_MODULES
will be loaded.
EMQX_LOADED_MODULES="emqx_mod_delayed,emqx_mod_rewrite"
EMQX_LOADED_MODULES="emqx_mod_delayed emqx_mod_rewrite"
EMQX_LOADED_MODULES="emqx_mod_delayed | emqx_mod_rewrite"
Oprtions | Default | Description |
---|---|---|
EMQX_LOADED_PLUGINS | see content below | default plugins emqx loaded |
Default environment variable EMQX_LOADED_PLUGINS
, including
emqx_recon
emqx_retainer
emqx_management
emqx_dashboard
# The default EMQX_LOADED_PLUGINS env
EMQX_LOADED_PLUGINS="emqx_recon,emqx_retainer,emqx_management,emqx_dashboard"
For example, set EMQX_LOADED_PLUGINS= emqx_auth_redis,emqx_auth_mysql
to load these two plugins.
You can use comma, space or other separator that you want.
All the plugins defined in EMQX_LOADED_PLUGINS
will be loaded.
EMQX_LOADED_PLUGINS="emqx_auth_redis,emqx_auth_mysql"
EMQX_LOADED_PLUGINS="emqx_auth_redis emqx_auth_mysql"
EMQX_LOADED_PLUGINS="emqx_auth_redis | emqx_auth_mysql"
The environment variables which with EMQX_
prefix are mapped to all emqx plugins' configuration file, .
get replaced by __
.
Example:
EMQX_AUTH__REDIS__SERVER <--> auth.redis.server
EMQX_AUTH__REDIS__PASSWORD <--> auth.redis.password
Don't worry about where to find the configuration file of emqx plugins, this docker image will find and config them automatically using some magic.
All plugin of emqx project could config in this way, following the environment variables mapping rule above.
Assume you are using redis auth plugin, for example:
#EMQX_AUTH__REDIS__SERVER="redis.at.yourserver"
#EMQX_AUTH__REDIS__PASSWORD="password_for_redis"
docker run -d --name emqx -p 18083:18083 -p 1883:1883 -p 4369:4369 \
-e EMQX_LISTENER__TCP__EXTERNAL=1883 \
-e EMQX_LOADED_PLUGINS="emqx_auth_redis" \
-e EMQX_AUTH__REDIS__SERVER="your.redis.server:6379" \
-e EMQX_AUTH__REDIS__PASSWORD="password_for_redis" \
-e EMQX_AUTH__REDIS__PASSWORD_HASH=plain \
emqx/emqx:latest
Use MASK_CONFIG_FILTER
to hide senstive configuration values from leaking to logging system.
For example, set MASK_CONFIG_FILTER="password|token"
to hide all configuration names containing those keywords.
By default emqx masks the configuration using following filter "password|passwd|key|token|secret"
. Setting MASK_CONFIG_FILTER
will be merged with the default filter.
The configuration should match whole word (after splitting it by '.') with MASK_CONFIG_FILTER
. You can use commas, spaces or other required separators to separate different words.
EMQ X supports a variety of clustering methods, see our documentation for details.
Let's create a static node list cluster from docker-compose.
-
Create
docker-compose.yaml
:version: '3' services: emqx1: image: emqx/emqx:v4.0.0 environment: - "EMQX_NAME=emqx" - "EMQX_HOST=node1.emqx.io" - "EMQX_CLUSTER__DISCOVERY=static" - "EMQX_CLUSTER__STATIC__SEEDS=emqx@node1.emqx.io, emqx@node2.emqx.io" networks: emqx-bridge: aliases: - node1.emqx.io emqx2: image: emqx/emqx:v4.0.0 environment: - "EMQX_NAME=emqx" - "EMQX_HOST=node2.emqx.io" - "EMQX_CLUSTER__DISCOVERY=static" - "EMQX_CLUSTER__STATIC__SEEDS=emqx@node1.emqx.io, emqx@node2.emqx.io" networks: emqx-bridge: aliases: - node2.emqx.io networks: emqx-bridge: driver: bridge
-
Start the docker-compose cluster
$ 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 => ['emqx@node1.emqx.io','emqx@node2.emqx.io'], stopped_nodes => []}
If you want to persist the EMQ X docker container, you need to keep the following directories:
/opt/emqx/data
/opt/emqx/etc
/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. In detail, one needs to specify the two environment variables: EMQX_NAME
and EMQX_HOST
, EMQX_HOST
set as 127.0.0.1
or network alias would be useful.
In if you use docker-compose, the configuration would look something like this:
volumes:
vol-emqx-data:
name: foo-emqx-data
vol-emqx-etc:
name: foo-emqx-etc
vol-emqx-log:
name: foo-emqx-log
services:
emqx:
image: emqx/emqx:v4.0.0
restart: always
environment:
EMQX_NAME: foo_emqx
EMQX_HOST: 127.0.0.1
volumes:
- vol-emqx-data:/opt/emqx/data
- vol-emqx-etc:/opt/emqx/etc
- vol-emqx-log:/opt/emqx/log
Under linux host machine, the easiest way is tuning host machine's kernel.
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 -p 4369:4369 \
--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/emqx:latest
REMEMBER: DO NOT RUN EMQ X DOCKER PRIVILEGED OR MOUNT SYSTEM PROC IN CONTAINER TO TUNE LINUX KERNEL, IT IS UNSAFE.