From 4e83ca34ce62c866a9f19bbc28e938840e08dfa0 Mon Sep 17 00:00:00 2001 From: Ivan Dyachkov Date: Tue, 18 Jun 2024 08:16:38 +0200 Subject: [PATCH] docs(docker): sync README.md with the official image docs --- deploy/docker/README.md | 73 ++++++++++++++++------------------------- 1 file changed, 28 insertions(+), 45 deletions(-) diff --git a/deploy/docker/README.md b/deploy/docker/README.md index 6a37fe979..44cb6c17c 100644 --- a/deploy/docker/README.md +++ b/deploy/docker/README.md @@ -50,20 +50,17 @@ 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. -The environment variables with `EMQX_` prefix are mapped to key-value pairs in configuration files. - Example: -```bash -EMQX_DASHBOARD__DEFAULT_PASSWORD <--> dashboard.default_password -EMQX_NODE__COOKIE <--> node.cookie -EMQX_LISTENERS__SSL__default__ENABLE <--> listeners.ssl.default.enable -``` + 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 -+ `__` is replaced with `.` +- Prefix `EMQX_` is removed +- All upper case letters are replaced with lower case letters +- `__` is replaced with `.` For example, set MQTT TCP port to 1883 @@ -71,38 +68,30 @@ For example, set MQTT TCP port to 1883 $ docker run -d --name emqx -e EMQX_DASHBOARD__DEFAULT_PASSWORD=mysecret -p 18083:18083 -p 1883:1883 emqx/emqx:latest ``` -Please read more about EMQX configuration in the [official documentation](https://www.emqx.io/docs/en/v5.0/configuration/configuration.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 -A node name consists of two parts, `EMQX_NAME` part and `EMQX_HOST` part connected by a the symbol `@`. For example: `emqx@127.0.0.1`. +Environment variable `EMQX_NODE__NAME` allows you to specify an EMQX node name, which defaults to `@`. -Environment variables `EMQX_NODE_NAME` or `EMQX_NODE__NAME` can be used to set a EMQX node name. -If neither of them is set, EMQX will resolve its node name from the running environment or other environment varialbes used for node discovery. - -When running in docker, by default, `EMQX_NAME` and `EMQX_HOST` are resolved as below: - -| Options | Default | Description | -| -------------| --------------- | -----------------------------| -| `EMQX_NAME` | container name | EMQX node short name | -| `EMQX_HOST` | container IP | EMQX node host, IP or FQDN | +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. -+ Create `docker-compose.yaml`: +- Create `docker-compose.yaml`: - ```yaml +```yaml version: '3' services: emqx1: image: emqx/emqx:latest environment: - - "EMQX_NODE_NAME=emqx@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: @@ -113,7 +102,7 @@ Let's create a static node list cluster from docker-compose. emqx2: image: emqx/emqx:latest environment: - - "EMQX_NODE_NAME=emqx@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,31 +113,30 @@ Let's create a static node list cluster from docker-compose. networks: emqx-bridge: driver: bridge - ``` +``` -+ Start the docker-compose cluster +- Start the docker-compose cluster - ```bash +```bash docker-compose -p my_emqx up -d - ``` +``` -+ View cluster +- View cluster - ```bash - $ docker exec -it my_emqx_emqx1_1 sh -c "emqx_ctl cluster status" +```bash + $ 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 => []} - ``` +``` ### Persistence 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` +- `/opt/emqx/data` +- `/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: @@ -156,8 +144,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 @@ -166,18 +152,15 @@ services: image: emqx/emqx:latest restart: always environment: - EMQX_NODE_NAME: foo_emqx@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).