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

docs: update docker documentation 

- loaded plugins and loaded modules are not applicable in 5.0
- add information on how to correctly persist configuration in `/etc/`
- remove --platform arg from Dockerfile
- update documentation links in charts readme
This commit is contained in:
Ivan Dyachkov 2023-01-18 10:37:42 +01:00
parent 4dd6e06680
commit dcb2fd2daf
4 changed files with 17 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
deploy/charts/emqx/README.md
View File

@ -102,10 +102,9 @@ The following table lists the configurable [EMQX](https://www.emqx.io/)-specific
default values. default values.
Parameter | Description | Default Value Parameter | Description | Default Value
--- | --- | --- --- | --- | ---
`emqxConfig` | Map of [configuration](https://www.emqx.io/docs/en/latest/configuration/configuration.html) items `emqxConfig` | Map of [configuration](https://www.emqx.io/docs/en/v5.0/admin/cfg.html) items
expressed as [environment variables](https://www.emqx.io/docs/en/v4.3/configuration/environment-variable.html) (prefix expressed as [environment variables](https://www.emqx.io/docs/en/v5.0/admin/cfg.html#environment-variables) (prefix `EMQX_` can be omitted) or using the configuration
can be omitted) or using the configuration files [namespaced dotted notation](https://www.emqx.io/docs/en/v5.0/admin/cfg.html#syntax) | `nil`
files [namespaced dotted notation](https://www.emqx.io/docs/en/latest/configuration/configuration.html) | `nil`
`emqxLicenseSecretName` | Name of the secret that holds the license information | `nil` `emqxLicenseSecretName` | Name of the secret that holds the license information | `nil`
## SSL settings ## SSL settings

3
deploy/docker/Dockerfile
View File

@ -1,7 +1,6 @@
ARG BUILD_FROM=ghcr.io/emqx/emqx-builder/5.0-26:1.13.4-24.3.4.2-1-debian11 ARG BUILD_FROM=ghcr.io/emqx/emqx-builder/5.0-26:1.13.4-24.3.4.2-1-debian11
ARG RUN_FROM=debian:11-slim ARG RUN_FROM=debian:11-slim
ARG BUILDPLATFORM=linux/amd64 FROM ${BUILD_FROM} AS builder
FROM --platform=$BUILDPLATFORM ${BUILD_FROM} AS builder
COPY . /emqx COPY . /emqx

3
deploy/docker/Dockerfile.alpine
View File

@ -1,7 +1,6 @@
ARG BUILD_FROM=ghcr.io/emqx/emqx-builder/5.0-26:1.13.4-24.3.4.2-1-alpine3.15.1 ARG BUILD_FROM=ghcr.io/emqx/emqx-builder/5.0-26:1.13.4-24.3.4.2-1-alpine3.15.1
ARG RUN_FROM=alpine:3.15.1 ARG RUN_FROM=alpine:3.15.1
ARG BUILDPLATFORM=linux/amd64 FROM ${BUILD_FROM} AS builder
FROM --platform=$BUILDPLATFORM ${BUILD_FROM} AS builder
RUN apk add --no-cache \ RUN apk add --no-cache \
autoconf \ autoconf \

136
deploy/docker/README.md
View File

@ -48,7 +48,7 @@ The EMQX broker runs as Linux user `emqx` in the docker container.
### Configuration ### 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. By default, the environment variables with `EMQX_` prefix are mapped to key-value pairs in configuration files.
@ -70,142 +70,28 @@ If `HOCON_ENV_OVERRIDE_PREFIX=DEV_` is set:
```bash ```bash
DEV_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors DEV_LISTENER__SSL__EXTERNAL__ACCEPTORS <--> listener.ssl.external.acceptors
DEV_MQTT__MAX_PACKET_SIZE <--> mqtt.max_packet_size 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 ```console
EMQX_NAME $ docker run -d --name emqx -e DEV_LISTENERS__TCP__DEFAULT__BIND=1883 -p 18083:18083 -p 1883:1883 emqx/emqx:latest
EMQX_HOST
``` ```
These environment variables will ignore for configuration file. Please read more about EMQX configuration in the [official documentation](https://www.emqx.io/docs/en/v5.0/admin/cfg.html).
#### EMQX Configuration #### EMQX node name 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 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. These environment variables are used during container startup phase only in [docker-entrypoint.sh](./docker-entrypoint.sh).
If set `EMQX_NAME` and `EMQX_HOST`, and unset `EMQX_NODE_NAME`, `EMQX_NODE_NAME=$EMQX_NAME@$EMQX_HOST`. 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.
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 emqx/emqx: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"
```
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 \
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 unique number for its own configuration option:
```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__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"}' \
emqx/emqx:latest
```
### Cluster ### Cluster
@ -296,6 +182,8 @@ services:
- vol-emqx-log:/opt/emqx/log - 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 ### Kernel Tuning
Under Linux host machine, the easiest way is [Tuning guide](https://www.emqx.io/docs/en/latest/deploy/tune.html). Under Linux host machine, the easiest way is [Tuning guide](https://www.emqx.io/docs/en/latest/deploy/tune.html).