docs(docker): sync README.md with the official image docs

This commit is contained in:
Ivan Dyachkov 2024-06-18 08:16:38 +02:00
parent a5110da37c
commit 4e83ca34ce
1 changed files with 28 additions and 45 deletions

View File

@ -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. 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: Example:
```bash EMQX_DASHBOARD__DEFAULT_PASSWORD <--> dashboard.default_password
EMQX_DASHBOARD__DEFAULT_PASSWORD <--> dashboard.default_password EMQX_NODE__COOKIE <--> node.cookie
EMQX_NODE__COOKIE <--> node.cookie EMQX_LISTENERS__SSL__default__ENABLE <--> listeners.ssl.default.enable
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. 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 - 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 `.` - `__` is replaced with `.`
For example, set MQTT TCP port to 1883 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 $ 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 #### 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 `<container_name>@<container_ip>`.
Environment variables `EMQX_NODE_NAME` or `EMQX_NODE__NAME` can be used to set a EMQX node name. If not specified, EMQX determines its node name based on the running environment or other environment variables used for node discovery.
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 |
### Cluster ### 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. Let's create a static node list cluster from docker-compose.
+ Create `docker-compose.yaml`: - Create `docker-compose.yaml`:
```yaml ```yaml
version: '3' version: '3'
services: services:
emqx1: emqx1:
image: emqx/emqx:latest image: emqx/emqx:latest
environment: environment:
- "EMQX_NODE_NAME=emqx@node1.emqx.io" - "EMQX_NODE__NAME=emqx@node1.emqx.io"
- "EMQX_CLUSTER__DISCOVERY_STRATEGY=static" - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
- "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]" - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]"
networks: networks:
@ -113,7 +102,7 @@ Let's create a static node list cluster from docker-compose.
emqx2: emqx2:
image: emqx/emqx:latest image: emqx/emqx:latest
environment: environment:
- "EMQX_NODE_NAME=emqx@node2.emqx.io" - "EMQX_NODE__NAME=emqx@node2.emqx.io"
- "EMQX_CLUSTER__DISCOVERY_STRATEGY=static" - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
- "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]" - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]"
networks: networks:
@ -124,31 +113,30 @@ Let's create a static node list cluster from docker-compose.
networks: networks:
emqx-bridge: emqx-bridge:
driver: bridge driver: bridge
``` ```
+ Start the docker-compose cluster - Start the docker-compose cluster
```bash ```bash
docker-compose -p my_emqx up -d docker-compose -p my_emqx up -d
``` ```
+ View cluster - View cluster
```bash ```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'], Cluster status: #{running_nodes => ['emqx@node1.emqx.io','emqx@node2.emqx.io'],
stopped_nodes => []} stopped_nodes => []}
``` ```
### Persistence ### Persistence
If you want to persist the EMQX docker container, you need to keep the following directories: If you want to persist the EMQX docker container, you need to keep the following directories:
+ `/opt/emqx/data` - `/opt/emqx/data`
+ `/opt/emqx/etc` - `/opt/emqx/log`
+ `/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: 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: volumes:
vol-emqx-data: vol-emqx-data:
name: foo-emqx-data name: foo-emqx-data
vol-emqx-etc:
name: foo-emqx-etc
vol-emqx-log: vol-emqx-log:
name: foo-emqx-log name: foo-emqx-log
@ -166,18 +152,15 @@ services:
image: emqx/emqx:latest image: emqx/emqx:latest
restart: always restart: always
environment: environment:
EMQX_NODE_NAME: foo_emqx@127.0.0.1 EMQX_NODE__NAME: foo_emqx@127.0.0.1
volumes: volumes:
- vol-emqx-data:/opt/emqx/data - vol-emqx-data:/opt/emqx/data
- vol-emqx-etc:/opt/emqx/etc
- 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://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). If you want tune Linux kernel by docker, you must ensure your docker is latest version (>=1.12).