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
``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.