From 9106efc310b6f8d2621ea169370f4ef898ceaa62 Mon Sep 17 00:00:00 2001 From: Ivan Dyachkov Date: Thu, 13 Jun 2024 19:37:59 +0200 Subject: [PATCH] update emqx content (#2452) * update emqx content * emqx: address review comments --- emqx/content.md | 59 ++++++++++++++----------------------------------- 1 file changed, 17 insertions(+), 42 deletions(-) diff --git a/emqx/content.md b/emqx/content.md index 97327c0cf..a2a612bb5 100644 --- a/emqx/content.md +++ b/emqx/content.md @@ -32,51 +32,35 @@ The EMQX broker runs as Linux user `emqx` in the 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. - -You can change the prefix by overriding `HOCON_ENV_OVERRIDE_PREFIX`. - Example: -```bash -EMQX_LISTENERS__SSL__DEFAULT__ACCEPTORS <--> listeners.ssl.default.acceptors -EMQX_ZONES__DEFAULT__MQTT__MAX_PACKET_SIZE <--> zones.default.mqtt.max_packet_size -``` + EMQX_DASHBOARD__DEFAULT_PASSWORD <--> dashboard.default_password + EMQX_NODE__COOKIE <--> node.cookie + EMQX_LISTENERS__SSL__default__ENABLE <--> listeners.ssl.default.enable + +Note: The lowercase use of 'default' is not a typo. It is used to demonstrate that lowercase environment variables are equivalent. - Prefix `EMQX_` is removed -- All upper case letters is replaced with lower case letters +- All upper case letters are replaced with lower case letters - `__` is replaced with `.` -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 -``` - For example, set MQTT TCP port to 1883 ```console -$ docker run -d --name emqx -e DEV_LISTENERS__TCP__DEFAULT__BIND=1883 -p 18083:18083 -p 1883:1883 %%IMAGE%%:latest +$ docker run -d --name emqx -e EMQX_DASHBOARD__DEFAULT_PASSWORD=mysecret -p 18083:18083 -p 1883:1883 %%IMAGE%%:latest ``` -Please read more about EMQX configuration in the [official documentation](https://www.emqx.io/docs/en/v5.0/admin/cfg.html). +Please read more about EMQX configuration in the [official documentation](https://docs.emqx.com/en/emqx/latest/configuration/configuration.html) #### 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 | +Environment variable `EMQX_NODE__NAME` allows you to specify an EMQX node name, which defaults to `@`. -These environment variables are used during container startup phase only in [docker-entrypoint.sh](./docker-entrypoint.sh). - -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. +If not specified, EMQX determines its node name based on the running environment or other environment variables used for node discovery. ### Cluster -EMQX supports a variety of clustering methods, see our [documentation](https://www.emqx.io/docs/en/latest/deploy/cluster/intro.html) for details. +EMQX supports a variety of clustering methods, see our [documentation](https://docs.emqx.com/en/emqx/latest/deploy/cluster/create-cluster.html) for details. Let's create a static node list cluster from docker-compose. @@ -89,8 +73,7 @@ Let's create a static node list cluster from docker-compose. emqx1: image: %%IMAGE%%:latest environment: - - "EMQX_NAME=emqx" - - "EMQX_HOST=node1.emqx.io" + - "EMQX_NODE__NAME=emqx@node1.emqx.io" - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static" - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]" networks: @@ -101,8 +84,7 @@ Let's create a static node list cluster from docker-compose. emqx2: image: %%IMAGE%%:latest environment: - - "EMQX_NAME=emqx" - - "EMQX_HOST=node2.emqx.io" + - "EMQX_NODE__NAME=emqx@node2.emqx.io" - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static" - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]" networks: @@ -124,7 +106,7 @@ Let's create a static node list cluster from docker-compose. - View cluster ```bash - $ docker exec -it my_emqx_emqx1_1 sh -c "emqx_ctl cluster status" + $ docker exec -it my_emqx_emqx1_1 sh -c "emqx ctl cluster status" Cluster status: #{running_nodes => ['emqx@node1.emqx.io','emqx@node2.emqx.io'], stopped_nodes => []} ``` @@ -134,10 +116,9 @@ Let's create a static node list cluster from docker-compose. If you want to persist the EMQX docker container, you need to keep the following directories: - `/opt/emqx/data` -- `/opt/emqx/etc` - `/opt/emqx/log` -Since data in these folders are partially stored under the `/opt/emqx/data/mnesia/${node_name}`, the user also needs to reuse the same node name to see the previous state. In detail, one needs to specify the two environment variables: `EMQX_NAME` and `EMQX_HOST`, `EMQX_HOST` set as `127.0.0.1` or network alias would be useful. +Since data in these folders are partially stored under the `/opt/emqx/data/mnesia/${node_name}`, the user also needs to reuse the same node name to see the previous state. To make this work, one needs to set the host part of `EMQX_NODE__NAME` to something static that does not change when you restart or recreate the container. It could be container name, hostname or loopback IP address `127.0.0.1` if you only have one node. In if you use docker-compose, the configuration would look something like this: @@ -145,8 +126,6 @@ In if you use docker-compose, the configuration would look something like this: volumes: vol-emqx-data: name: foo-emqx-data - vol-emqx-etc: - name: foo-emqx-etc vol-emqx-log: name: foo-emqx-log @@ -155,19 +134,15 @@ services: image: %%IMAGE%%:latest restart: always environment: - EMQX_NAME: foo_emqx - EMQX_HOST: 127.0.0.1 + EMQX_NODE__NAME: foo_emqx@127.0.0.1 volumes: - vol-emqx-data:/opt/emqx/data - - vol-emqx-etc:/opt/emqx/etc - 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). +Under Linux host machine, the easiest way is [Tuning guide](https://docs.emqx.com/en/emqx/latest/performance/tune.html). If you want tune Linux kernel by docker, you must ensure your docker is latest version (>=1.12).