轻量级物联网开源平台，快速部署，千万级设备承载、电信级稳定性 物模型-规则引擎-数据通道-组态页面全流程低代码开发、前后端完全开

# Quick reference + **Where to get help**: https://emqx.io or https://github.com/emqx/emqx + **Where to file issues:** https://github.com/emqx/emqx/issues + **Supported architectures** `amd64`, `arm64v8`, `arm32v7`, `i386`, `s390x` + **Supported Docker versions**: [the latest release](https://github.com/docker/docker-ce/releases/latest) # What is EMQX [EMQX MQTT broker](https://emqx.io/products/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, *EMQX* 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 *EMQX* broker can scaled to 10+ million concurrent MQTT connections on one cluster. # How to use this image ### Run emqx 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. ### Configuration Use the environment variable to configure the EMQX docker container. By default, the environment variables with ``EMQX_`` prefix are mapped to key-value pairs in configuration files. You can change the prefix by overriding "CUTTLEFISH_ENV_OVERRIDE_PREFIX". Example: ```bash EMQX_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors EMQX_MQTT__MAX_PACKET_SIZE <--> mqtt.max_packet_size ``` + Prefix ``EMQX_`` is removed + All upper case letters is replaced with lower case letters + ``__`` is replaced with ``.`` If `CUTTLEFISH_ENV_OVERRIDE_PREFIX=DEV_` is set: ```bash DEV_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors DEV_MQTT__MAX_PACKET_SIZE <--> mqtt.max_packet_size ``` Non mapped environment variables: ```bash EMQX_NAME EMQX_HOST ``` These environment variables will ignore for configuration file. #### EMQX Configuration > NOTE: All EMQX Configuration in [etc/emqx.conf](https://github.com/emqx/emqx/blob/main-v4.3/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 | The list is incomplete and may changed with [etc/emqx.conf](https://github.com/emqx/emqx/blob/main-v4.3/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`` #### EMQ Loaded Modules Configuration | 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`` ```bash # 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. ```bash 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" ``` #### EMQ Loaded Plugins Configuration | 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_rule_engine`` + ``emqx_management`` + ``emqx_dashboard`` ```bash # 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. ```bash 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" ``` #### EMQX Plugins Configuration The environment variables which with ``EMQX_`` prefix are mapped to all emqx plugins' configuration file, ``.`` get replaced by ``__``. Example: ```bash 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: ```bash #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 ``` For numbered configuration options where the number is next to a ``.`` such as: + backend.redis.pool1.server + backend.redis.hook.message.publish.1 You can configure an arbitrary number of them as long as each has a uniq unber for it's own configuration option: ```bash docker run -d --name emqx -p 18083:18083 -p 1883:1883 -p 4369:4369 \ -e EMQX_BACKEND_REDIS_POOL1__SERVER=127.0.0.1:6379 [...] -e EMQX_BACKEND__REDIS__POOL5__SERVER=127.0.0.5:6379 -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__1='{"topic": "persistant/topic1", "action": {"function": "on_message_publish"}, "pool": "pool1"}' -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__2='{"topic": "persistant/topic2", "action": {"function": "on_message_publish"}, "pool": "pool1"}' -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__3='{"topic": "persistant/topic3", "action": {"function": "on_message_publish"}, "pool": "pool1"}' [...] -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__13='{"topic": "persistant/topic13", "action": {"function": "on_message_publish"}, "pool": "pool1"}' emqx/emqx:latest ``` ### Cluster EMQX supports a variety of clustering methods, see our [documentation](https://docs.emqx.io/broker/latest/en/advanced/cluster.html#emqx-service-discovery) for details. Let's create a static node list cluster from docker-compose. + Create `docker-compose.yaml`: ```yaml version: '3' services: emqx1: image: emqx/emqx:latest environment: - "EMQX_NAME=emqx" - "EMQX_HOST=node1.emqx.io" - "EMQX_CLUSTER__DISCOVERY=static" - "[email protected], emqx@node2.