Merge pull request #13286 from id/0718-sync-docker-docs-with-official-image
docs(docker): sync README.md with the official image docs
This commit is contained in:
Ivan Dyachkov
GitHub
commit
43cca6c9f8
|
|
@ -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).
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue