yuanbiao
/
emqx
1
0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs: fix minor issues in docker readme

This commit is contained in:
Ivan Dyachkov 2022-11-29 20:18:17 +01:00
parent e6e559710b
commit 6ced692ce6
1 changed files with 44 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

85
deploy/docker/README.md
View File

@ -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 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 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. 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. 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`. 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 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 + All upper case letters is replaced with lower case letters
+ ``__`` is replaced with ``.`` + `__` is replaced with `.`
If `HOCON_ENV_OVERRIDE_PREFIX=DEV_` is set: If `HOCON_ENV_OVERRIDE_PREFIX=DEV_` is set:
@ -75,41 +79,43 @@ These environment variables will ignore for configuration file.
#### EMQX Configuration #### 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 | | Options | Default | Mapped | Description |
| ---------------------------| ------------------ | ------------------------- | ------------------------------------- | | ---------------------------| ------------------ | ------------------------- | ------------------------------------- |
| `EMQX_NAME` | container name | none | EMQX node short name | | `EMQX_NAME` | container name | none | EMQX node short name |
| `EMQX_HOST` | container IP | none | EMQX node host, IP or FQDN | | `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 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 #### EMQX Loaded Modules Configuration
| Oprtions | Default | Description | | Options | Default | Description |
| ------------------------ | ------------------ | ------------------------------------- | | ----------------------- | ------------------ | ------------------------------------- |
| `EMQX_LOADED_MODULES` | see content below | default EMQX loaded modules | | `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 ```bash
# The default EMQX_LOADED_MODULES env # The default EMQX_LOADED_MODULES env
EMQX_LOADED_MODULES="emqx_mod_presence" 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. 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 ```bash
EMQX_LOADED_MODULES="emqx_mod_delayed,emqx_mod_rewrite" 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 #### EMQX Loaded Plugins Configuration
| Oprtions | Default | Description | | Options | Default | Description |
| ------------------------ | ------------------ | ------------------------------------- | | ----------------------- | ------------------ | ------------------------------------- |
| `EMQX_LOADED_PLUGINS` | see content below | default EMQX loaded plugins | | `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_recon`
+ ``emqx_retainer`` + `emqx_retainer`
+ ``emqx_rule_engine`` + `emqx_rule_engine`
+ ``emqx_management`` + `emqx_management`
+ ``emqx_dashboard`` + `emqx_dashboard`
```bash ```bash
# The default EMQX_LOADED_PLUGINS env # The default EMQX_LOADED_PLUGINS env
EMQX_LOADED_PLUGINS="emqx_recon,emqx_retainer,emqx_management,emqx_dashboard" 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. 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 ```bash
EMQX_LOADED_PLUGINS="emqx_retainer,emqx_rule_engine" EMQX_LOADED_PLUGINS="emqx_retainer,emqx_rule_engine"
@ -150,7 +156,7 @@ EMQX_LOADED_PLUGINS="emqx_retainer | emqx_rule_engine"
#### EMQX Plugins Configuration #### 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: Example:
@ -177,7 +183,7 @@ docker run -d --name emqx -p 18083:18083 -p 1883:1883 \
emqx/emqx:latest 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.pool1.server
+ backend.redis.hook.message.publish.1 + 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 ```bash
docker run -d --name emqx -p 18083:18083 -p 1883:1883 \ 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__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__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__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__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 emqx/emqx:latest
``` ```
### Cluster ### 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. 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: networks:
emqx-bridge: emqx-bridge:
driver: bridge driver: bridge
``` ```
+ Start the docker-compose cluster + Start the docker-compose cluster
@ -276,7 +281,7 @@ volumes:
services: services:
emqx: emqx:
image: emqx/emqx:v4.0.0 image: emqx/emqx:latest
restart: always restart: always
environment: environment:
EMQX_NAME: foo_emqx EMQX_NAME: foo_emqx
@ -289,12 +294,11 @@ services:
### Kernel Tuning ### 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). If you want tune Linux kernel by docker, you must ensure your docker is latest version (>=1.12).
```bash ```bash
docker run -d --name emqx -p 18083:18083 -p 1883:1883 \ docker run -d --name emqx -p 18083:18083 -p 1883:1883 \
--sysctl fs.file-max=2097152 \ --sysctl fs.file-max=2097152 \
--sysctl fs.nr_open=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_max_tw_buckets=1048576 \
--sysctl net.ipv4.tcp_fin_timeout=15 \ --sysctl net.ipv4.tcp_fin_timeout=15 \
emqx/emqx:latest emqx/emqx:latest
``` ```
> REMEMBER: DO NOT RUN EMQX DOCKER PRIVILEGED OR MOUNT SYSTEM PROC IN CONTAINER TO TUNE LINUX KERNEL, IT IS UNSAFE. > REMEMBER: DO NOT RUN EMQX DOCKER PRIVILEGED OR MOUNT SYSTEM PROC IN CONTAINER TO TUNE LINUX KERNEL, IT IS UNSAFE.