From dcb2fd2daf6d734b7650c0dc362823263ed72a67 Mon Sep 17 00:00:00 2001 From: Ivan Dyachkov Date: Wed, 18 Jan 2023 10:37:42 +0100 Subject: [PATCH] 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 --- deploy/charts/emqx/README.md | 7 +- deploy/docker/Dockerfile | 3 +- deploy/docker/Dockerfile.alpine | 3 +- deploy/docker/README.md | 136 +++----------------------------- 4 files changed, 17 insertions(+), 132 deletions(-) diff --git a/deploy/charts/emqx/README.md b/deploy/charts/emqx/README.md index b07bf35ae..1a2090320 100644 --- a/deploy/charts/emqx/README.md +++ b/deploy/charts/emqx/README.md @@ -102,10 +102,9 @@ The following table lists the configurable [EMQX](https://www.emqx.io/)-specific default values. Parameter | Description | Default Value --- | --- | --- -`emqxConfig` | Map of [configuration](https://www.emqx.io/docs/en/latest/configuration/configuration.html) items -expressed as [environment variables](https://www.emqx.io/docs/en/v4.3/configuration/environment-variable.html) (prefix -can be omitted) or using the configuration -files [namespaced dotted notation](https://www.emqx.io/docs/en/latest/configuration/configuration.html) | `nil` +`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/v5.0/admin/cfg.html#environment-variables) (prefix `EMQX_` can be omitted) or using the configuration +files [namespaced dotted notation](https://www.emqx.io/docs/en/v5.0/admin/cfg.html#syntax) | `nil` `emqxLicenseSecretName` | Name of the secret that holds the license information | `nil` ## SSL settings diff --git a/deploy/docker/Dockerfile b/deploy/docker/Dockerfile index 03533eec4..4a00c68fb 100644 --- a/deploy/docker/Dockerfile +++ b/deploy/docker/Dockerfile @@ -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 RUN_FROM=debian:11-slim -ARG BUILDPLATFORM=linux/amd64 -FROM --platform=$BUILDPLATFORM ${BUILD_FROM} AS builder +FROM ${BUILD_FROM} AS builder COPY . /emqx diff --git a/deploy/docker/Dockerfile.alpine b/deploy/docker/Dockerfile.alpine index ebce2f539..0f72be9ab 100644 --- a/deploy/docker/Dockerfile.alpine +++ b/deploy/docker/Dockerfile.alpine @@ -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 RUN_FROM=alpine:3.15.1 -ARG BUILDPLATFORM=linux/amd64 -FROM --platform=$BUILDPLATFORM ${BUILD_FROM} AS builder +FROM ${BUILD_FROM} AS builder RUN apk add --no-cache \ autoconf \ diff --git a/deploy/docker/README.md b/deploy/docker/README.md index c6ffb2559..e6067a203 100644 --- a/deploy/docker/README.md +++ b/deploy/docker/README.md @@ -48,7 +48,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. @@ -70,142 +70,28 @@ 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 emqx/emqx:latest ``` -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 - -> 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. +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`. - -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 -``` +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 @@ -296,6 +182,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).