Deploy with Docker

This chapter introduces how to use the official Docker image to install and run EMQX, and how to use Docker Compose to build an EMQX cluster.

Note

  1. If you want to keep the data, mount the EMQX data directory (/opt/emqx/data) out of the container, so that the data will persist even if the container no longer exists.

  2. In Docker, localhost or 127.0.0.1 points to the internal address of the container. Use the host’s IP or host networkingDeploy with Docker - 图1 (opens new window) to access the host address. If you are using Docker for Mac or Docker for Windows, you can use host.docker.internal as the host address.

Use Docker to Run A Single EMQX Node

This section will introduce how to use the Docker image to install the latest version of EMQX. If you want to work with other versions, please visit the EMQX Deployment pageDeploy with Docker - 图2 (opens new window).

  1. To get the Docker image, run:
  1. docker pull emqx/emqx:5.1.0
  1. To start the Docker container, run:
  1. docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 8084:8084 -p 8883:8883 -p 18083:18083  emqx:5.1.0

For more information about EMQX official docker image, see Docker Hub - emqxDeploy with Docker - 图3 (opens new window).

Use Docker Compose to Build an EMQX Cluster

Docker Compose is a tool for defining and running multi-container Docker applications. This section introduces how to use Docker Compose to create a static EMQX cluster.

TIP

Docker Compose is already included in Docker Desktop. If your Docker Compose still needs to be installed, you may refer to Install Docker ComposeDeploy with Docker - 图4 (opens new window) for detailed operating steps.

  1. Create a docker-compose.yml file under any directory with the following content:
  1. version: '3'
  3. services:
  4.   emqx1:
  5.     image: emqx:5.1.0
  6.     container_name: emqx1
  7.     environment:
  8.     - "EMQX_NODE_NAME=emqx@node1.emqx.io"
  9.     - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
  10.     - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io,emqx@node2.emqx.io]"
  11.     healthcheck:
  12.       test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
  13.       interval: 5s
  14.       timeout: 25s
  15.       retries: 5
  16.     networks:
  17.       emqx-bridge:
  18.         aliases:
  19.         - node1.emqx.io
  20.     ports:
  21.       - 1883:1883
  22.       - 8083:8083
  23.       - 8084:8084
  24.       - 8883:8883
  25.       - 18083:18083 
  26.     # volumes:
  27.     #   - $PWD/emqx1_data:/opt/emqx/data
  29.   emqx2:
  30.     image: emqx:5.1.0
  31.     container_name: emqx2
  32.     environment:
  33.     - "EMQX_NODE_NAME=emqx@node2.emqx.io"
  34.     - "EMQX_CLUSTER__DISCOVERY_STRATEGY=static"
  35.     - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io,emqx@node2.emqx.io]"
  36.     healthcheck:
  37.       test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
  38.       interval: 5s
  39.       timeout: 25s
  40.       retries: 5
  41.     networks:
  42.       emqx-bridge:
  43.         aliases:
  44.         - node2.emqx.io
  45.     # volumes:
  46.     #   - $PWD/emqx2_data:/opt/emqx/data
  48. networks:
  49.   emqx-bridge:
  50.     driver: bridge
  1. In the command line tool, switch to the directory where docker-compose.yml is stored, and run the following command to start the EMQX cluster:
  1. docker-compose up -d
  1. To check the cluster status, run:
  1. $ docker exec -it emqx1 sh -c "emqx_ctl cluster status"
  2. Cluster status: #{running_nodes => ['emqx@node1.emqx.com','emqx@node2.emqx.com'],
  3.                   stopped_nodes => []}

Next

Use an MQTT client to connect EMQX for message publish/subscribe. For more information, see Publish and Subscribe.

  • On how to configure EMQX parameters and other features, see Configuration.

  • On how to build an EMQX cluster with multiple nodes, see Clustering.