From 6ced692ce6c07474f5e0ddfa11fccef2d246129f Mon Sep 17 00:00:00 2001 From: Ivan Dyachkov Date: Tue, 29 Nov 2022 20:18:17 +0100 Subject: [PATCH] docs: fix minor issues in docker readme --- deploy/docker/README.md | 85 +++++++++++++++++++++-------------------- 1 file changed, 44 insertions(+), 41 deletions(-) diff --git a/deploy/docker/README.md b/deploy/docker/README.md index d2d729b5d..51d53d1e3 100644 --- a/deploy/docker/README.md +++ b/deploy/docker/README.md @@ -30,11 +30,15 @@ Starting from 3.0 release, *EMQX* broker fully supports MQTT V5.0 protocol speci Execute some command under this docker image -``docker run -d --name emqx emqx/emqx:$(tag)`` +```console +$ docker run -d --name emqx emqx/emqx:${tag} +``` For example -``docker run -d --name emqx -p 18083:18083 -p 1883:1883 emqx/emqx:latest`` +```console +$ 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. @@ -42,7 +46,7 @@ The EMQX broker runs as Linux user `emqx` in the docker container. 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. +By default, the environment variables with `EMQX_` prefix are mapped to key-value pairs in configuration files. You can change the prefix by overriding `HOCON_ENV_OVERRIDE_PREFIX`. @@ -53,9 +57,9 @@ EMQX_LISTENERS__SSL__DEFAULT__ACCEPTORS <--> listeners.ssl.default.acceptors EMQX_ZONES__DEFAULT__MQTT__MAX_PACKET_SIZE <--> zones.default.mqtt.max_packet_size ``` -+ Prefix ``EMQX_`` is removed ++ Prefix `EMQX_` is removed + All upper case letters is replaced with lower case letters -+ ``__`` is replaced with ``.`` ++ `__` is replaced with `.` If `HOCON_ENV_OVERRIDE_PREFIX=DEV_` is set: @@ -75,41 +79,43 @@ These environment variables will ignore for configuration file. #### EMQX Configuration -> NOTE: All EMQX Configuration in [`etc/emqx.conf`](https://github.com/emqx/emqx/blob/master/etc/emqx.conf) can be configured via environment variables. The following list is just an example, not a complete configuration. +> 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. | 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/master/etc/emqx.conf) and plugin configuration files. But the mapping rule is similar. +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``. +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__LISTENERS__TCP__DEFAULT__BIND=1883 -p 18083:18083 -p 1883:1883 emqx/emqx:latest`` +```console +$ docker run -d --name emqx -e EMQX__LISTENERS__TCP__DEFAULT__BIND=1883 -p 18083:18083 -p 1883:1883 emqx/emqx:latest +``` #### EMQX Loaded Modules Configuration -| Oprtions | Default | Description | -| ------------------------ | ------------------ | ------------------------------------- | -| `EMQX_LOADED_MODULES` | see content below | default EMQX loaded modules | +| Options | Default | Description | +| ----------------------- | ------------------ | ------------------------------------- | +| `EMQX_LOADED_MODULES` | see content below | default EMQX loaded modules | -Default environment variable ``EMQX_LOADED_MODULES``, including +Default environment variable `EMQX_LOADED_MODULES`, including -+ ``emqx_mod_presence`` ++ `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. +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. +All the modules defined in env `EMQX_LOADED_MODULES` will be loaded. ```bash EMQX_LOADED_MODULES="emqx_mod_delayed,emqx_mod_rewrite" @@ -119,28 +125,28 @@ EMQX_LOADED_MODULES="emqx_mod_delayed | emqx_mod_rewrite" #### EMQX Loaded Plugins Configuration -| Oprtions | Default | Description | -| ------------------------ | ------------------ | ------------------------------------- | -| `EMQX_LOADED_PLUGINS` | see content below | default EMQX loaded plugins | +| Options | Default | Description | +| ----------------------- | ------------------ | ------------------------------------- | +| `EMQX_LOADED_PLUGINS` | see content below | default EMQX loaded plugins | -Default environment variable ``EMQX_LOADED_PLUGINS``, including +Default environment variable `EMQX_LOADED_PLUGINS`, including -+ ``emqx_recon`` -+ ``emqx_retainer`` -+ ``emqx_rule_engine`` -+ ``emqx_management`` -+ ``emqx_dashboard`` ++ `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_retainer,emqx_rule_engine`` to load these two plugins. +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. +All the plugins defined in `EMQX_LOADED_PLUGINS` will be loaded. ```bash EMQX_LOADED_PLUGINS="emqx_retainer,emqx_rule_engine" @@ -150,7 +156,7 @@ 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 ``__``. +The environment variables which with `EMQX_` prefix are mapped to all EMQX plugins' configuration file, `.` get replaced by `__`. Example: @@ -177,7 +183,7 @@ docker run -d --name emqx -p 18083:18083 -p 1883:1883 \ emqx/emqx:latest ``` -For numbered configuration options where the number is next to a ``.`` such as: +For numbered configuration options where the number is next to a `.` such as: + backend.redis.pool1.server + backend.redis.hook.message.publish.1 @@ -186,20 +192,20 @@ You can configure an arbitrary number of them as long as each has a unique numbe ```bash docker run -d --name emqx -p 18083:18083 -p 1883:1883 \ - -e EMQX_BACKEND_REDIS_POOL1__SERVER=127.0.0.1:6379 + -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__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"}' + -e EMQX_BACKEND__REDIS__HOOK_MESSAGE__PUBLISH__13='{"topic": "persistent/topic13", "action": {"function": "on_message_publish"}, "pool": "pool1"}' \ emqx/emqx:latest ``` ### Cluster -EMQX supports a variety of clustering methods, see our [documentation](https://www.emqx.io/docs/en/latest/advanced/cluster.html) for details. +EMQX supports a variety of clustering methods, see our [documentation](https://www.emqx.io/docs/en/latest/deploy/cluster/intro.html) for details. Let's create a static node list cluster from docker-compose. @@ -236,7 +242,6 @@ Let's create a static node list cluster from docker-compose. networks: emqx-bridge: driver: bridge - ``` + Start the docker-compose cluster @@ -276,7 +281,7 @@ volumes: services: emqx: - image: emqx/emqx:v4.0.0 + image: emqx/emqx:latest restart: always environment: EMQX_NAME: foo_emqx @@ -289,12 +294,11 @@ services: ### Kernel Tuning -Under Linux host machine, the easiest way is [Tuning guide](https://www.emqx.io/docs/en/latest/tutorial/tune.html). +Under Linux host machine, the easiest way is [Tuning guide](https://www.emqx.io/docs/en/latest/deploy/tune.html). If you want tune Linux kernel by docker, you must ensure your docker is latest version (>=1.12). ```bash - docker run -d --name emqx -p 18083:18083 -p 1883:1883 \ --sysctl fs.file-max=2097152 \ --sysctl fs.nr_open=2097152 \ @@ -312,7 +316,6 @@ docker run -d --name emqx -p 18083:18083 -p 1883:1883 \ --sysctl net.ipv4.tcp_max_tw_buckets=1048576 \ --sysctl net.ipv4.tcp_fin_timeout=15 \ emqx/emqx:latest - ``` > REMEMBER: DO NOT RUN EMQX DOCKER PRIVILEGED OR MOUNT SYSTEM PROC IN CONTAINER TO TUNE LINUX KERNEL, IT IS UNSAFE.