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

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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
deploy/docker/README.md
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.
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 `<container_name>@<container_ip>`.
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).