Merge pull request #2267 from id/update-emqx-docs

update emqx docs

emqx/content.md

@@ -30,7 +30,7 @@ The EMQX broker runs as Linux user `emqx` in the docker container.
 
 ### Configuration
 
-Use the environment variable to configure the EMQX docker container.
+All EMQX Configuration in [`etc/emqx.conf`](https://github.com/emqx/emqx/blob/master/apps/emqx/etc/emqx.conf) can be configured via environment variables.
 
 By default, the environment variables with `EMQX_` prefix are mapped to key-value pairs in configuration files.
 
@@ -52,142 +52,27 @@ If `HOCON_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
+DEV_LISTENERS__TCP__DEFAULT__BIND      <--> listeners.tcp.default.bind
 ```
 
-Non mapped environment variables:
+For example, set MQTT TCP port to 1883
 
-```bash
-EMQX_NAME
-EMQX_HOST
+```console
+$ docker run -d --name emqx -e DEV_LISTENERS__TCP__DEFAULT__BIND=1883 -p 18083:18083 -p 1883:1883 %%IMAGE%%:latest
 ```
 
-These environment variables will ignore for configuration file.
-
-#### EMQX Configuration
+Please read more about EMQX configuration in the [official documentation](https://www.emqx.io/docs/en/v5.0/admin/cfg.html).
 
-> NOTE: All EMQX Configuration in [`etc/emqx.conf`](https://github.com/emqx/emqx/blob/master/apps/emqx/etc/emqx.conf) can be configured via environment variables. The following list is just an example, not a complete configuration.
+#### EMQX node name 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 be changed with [`etc/emqx.conf`](https://github.com/emqx/emqx/blob/master/apps/emqx/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
-
-```console
-$ docker run -d --name emqx -e EMQX__LISTENERS__TCP__DEFAULT__BIND=1883 -p 18083:18083 -p 1883:1883 %%IMAGE%%:latest
-```
-
-#### EMQX Loaded Modules Configuration
-
-| Options               | Default           | Description                 |
-|-----------------------|-------------------|-----------------------------|
-| `EMQX_LOADED_MODULES` | see content below | default EMQX loaded modules |
-
-Default environment variable `EMQX_LOADED_MODULES`, including
-
--	`emqx_mod_presence`
-
-```bash
-# The default EMQX_LOADED_MODULES env
-EMQX_LOADED_MODULES="emqx_mod_presence"
-```
-
-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"
-```
-
-#### EMQX Loaded Plugins Configuration
-
-| Options               | Default           | Description                 |
-|-----------------------|-------------------|-----------------------------|
-| `EMQX_LOADED_PLUGINS` | see content below | default EMQX loaded plugins |
-
-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"
-```
+These environment variables are used during container startup phase only in [docker-entrypoint.sh](./docker-entrypoint.sh).
 
-For example, set `EMQX_LOADED_PLUGINS= emqx_retainer,emqx_rule_engine` 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_retainer,emqx_rule_engine"
-EMQX_LOADED_PLUGINS="emqx_retainer emqx_rule_engine"
-EMQX_LOADED_PLUGINS="emqx_retainer | emqx_rule_engine"
-```
-
-#### EMQX Plugins Configuration
-
-The environment variables which with `EMQX_` prefix are mapped to all EMQX plugins' configuration file, `.` get replaced by `__`.
-
-Example:
-
-```bash
-EMQX_RETAINER__STORAGE_TYPE <--> retainer.storage_type
-EMQX_RETAINER__MAX_PAYLOAD_SIZE <--> retainer.max_payload_size
-```
-
-Don't worry about where to find the configuration file of EMQX plugins, this docker image will find and configure them automatically using some magic.
-
-All EMQX plugins can be configured this way, following the environment variables mapping rule above.
-
-Assume you are using Redis auth plugin, for example:
-
-```bash
-#EMQX_RETAINER__STORAGE_TYPE = "ram"
-#EMQX_RETAINER.MAX_PAYLOAD_SIZE = 1MB
-
-docker run -d --name emqx -p 18083:18083 -p 1883:1883 \
-    -e EMQX_LISTENERS__TCP__DEFAULT=1883 \
-    -e EMQX_LOADED_PLUGINS="emqx_retainer" \
-    -e EMQX_RETAINER__STORAGE_TYPE = "ram" \
-    -e EMQX_RETAINER__MAX_PAYLOAD_SIZE = 1MB \
-    %%IMAGE%%: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 unique number for its 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": "persistent/topic1", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \
-    -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__2='{"topic": "persistent/topic2", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \
-    -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__3='{"topic": "persistent/topic3", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \
-    [...]
-    -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__13='{"topic": "persistent/topic13", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \
-    %%IMAGE%%:latest
-```
+If `EMQX_NAME` and `EMQX_HOST` are set, and `EMQX_NODE_NAME` is not set, `EMQX_NODE_NAME=$EMQX_NAME@$EMQX_HOST`. Otherwise `EMQX_NODE_NAME` is taken verbatim.
 
 ### Cluster
 
@@ -278,6 +163,8 @@ services:
       - vol-emqx-log:/opt/emqx/log
 ```
 
+Note that `/opt/emqx/etc` contains some essential configuration files. If you want to mount a host directory in the container to persist configuration overrides, you will need to bootstrap it with [default configuration files](https://github.com/emqx/emqx/tree/master/apps/emqx/etc).
+
 ### Kernel Tuning
 
 Under Linux host machine, the easiest way is [Tuning guide](https://www.emqx.io/docs/en/latest/deploy/tune.html).