EMQX Edge

English

简体中文

English

简体中文

Appearance

Contact Us

Deploy EMQX Edge with Docker ​

This guide walks you through deploying EMQX Edge using the official Docker image. You will learn how to start EMQX Edge quickly and, if needed, load a custom configuration file when launching the container.

Prerequisites ​

Before you start, ensure that:

  • Docker is installed and running on your host machine.
  • The host machine has access to the Internet to pull images from Docker Hub.

Pull the EMQX Edge Docker Image ​

The following command uses 1.2.0 as an example. Replace this version number with the specific EMQX Edge release you want to deploy.

bash
docker pull emqx/emqx-edge:1.2.0

Note: EMQX Edge Docker images are architecture-specific.

  • For x86_64 platforms, use: emqx/emqx-edge:1.2.0.
  • For arm64 platforms, use: emqx/emqx-edge:1.2.0-arm64.

Example for pulling the arm64 image:

bash
docker pull emqx/emqx-edge:1.2.0-arm64

Start EMQX Edge Container ​

To start EMQX Edge with default settings, run the following command:

bash
docker run -d -it --name emqx-edge \
  -p 1883:1883 \
  -p 8081:8081 \
  -p 8083:8083 \
  -p 8086:8086 \
  -p 8883:8883 \
  emqx/emqx-edge:<version>

This command performs the following actions:

  • Creates and runs a detached container named emqx-edge.
  • Maps the default EMQX Edge service ports to the host system.
  • It uses the image tag <version>, which you should replace with the release you want to run.

You can check whether EMQX Edge is running by executing:

bash
docker ps

Expected output should show the emqx-edge container with Up status.

Use Architecture-Specific Image ​

If you are deploying on an arm64 device, replace the image tag in the command above as follows:

bash
docker run -d -it --name emqx-edge \
  -p 1883:1883 \
  -p 8081:8081 \
  -p 8083:8083 \
  -p 8086:8086 \
  -p 8883:8883 \
  emqx/emqx-edge:<version>-arm64

Start EMQX Edge with a Custom Configuration File ​

EMQX Edge stores its configuration files under the /opt/emqx-edge directory inside the container. The main configuration file is:

/opt/emqx-edge/nanomq.conf

Note: Configuration file details are covered in the Configuration section.

To start EMQX Edge using a custom configuration file located in the current directory, run:

bash
docker run -d -it --name emqx-edge \
  -v ./nanomq.conf:/opt/emqx-edge/nanomq.conf \
  -p 1883:1883 \
  -p 8081:8081 \
  -p 8083:8083 \
  -p 8086:8086 \
  -p 8883:8883 \
  emqx/emqx-edge:<version>

This command starts EMQX Edge with the following configuration:

  • It mounts your local nanomq.conf file into the container at /opt/emqx-edge/nanomq.conf, which is the stable configuration path used by EMQX Edge.
  • It ensures that your custom configuration overrides the default settings inside the container.
  • It starts EMQX Edge with the required MQTT and HTTP service ports exposed.

Verify the Deployment ​

After the container starts successfully, you can verify EMQX Edge status through:

  1. Docker logs

    bash
    docker logs emqx-edge

  2. Web Dashboard Open your browser and visit: http://localhost:8081. Log in with default credentials:

    • Username: admin
    • Password: public

If you can access the dashboard or see normal startup logs, your EMQX Edge deployment is successful.