# Installation

EMQX binary packages are released on below operating systems:

  • EL7 (RedHat 7, CentOS 7)
  • EL8 (RedHat 8, RockyLinux 8, AmazonLinux 2022)
  • Raspbian 10
  • Debian 9
  • Debian 10
  • Ubuntu 16.04
  • Ubuntu 18.04
  • Ubuntu 20.04
  • macOS 10
  • macOS 11
  • Windows Server 2019

# Running EMQX in Docker

# Run a single container

  1. Get docker image

    docker pull emqx/emqx:5.0.0
    
    1
  2. Start docker container

    docker run -d --name emqx -p 1883:1883 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 18083:18083 emqx/emqx:5.0.0
    
    1

# Create a simple static cluster by docker-compose

  1. Create docker-compose.yaml file

    version: '3'
    
    services:
      emqx1:
        image: emqx/emqx:5.0.0
        environment:
        - "EMQX_NODE_NAME=emqx@node1.emqx.io"
        - "EMQX_CLUSTER__DISCOVERY=static"
        - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io,emqx@node2.emqx.io]"
        healthcheck:
          test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
          interval: 5s
          timeout: 25s
          retries: 5
        networks:
          emqx-bridge:
            aliases:
            - node1.emqx.io
    
      emqx2:
        image: emqx/emqx:5.0.0
        environment:
        - "EMQX_NODE_NAME=emqx@node2.emqx.io"
        - "EMQX_CLUSTER__DISCOVERY=static"
        - "EMQX_CLUSTER__STATIC__SEEDS=[emqx@node1.emqx.io, emqx@node2.emqx.io]"
        healthcheck:
          test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
          interval: 5s
          timeout: 25s
          retries: 5
        networks:
          emqx-bridge:
            aliases:
            - node2.emqx.io
    
    networks:
      emqx-bridge:
        driver: bridge
    
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
  2. Start docker-compose cluster

    docker-compose -p my_emqx up -d
    
    1
  3. View cluster

    $ 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 => []}
    
    1
    2
    3

For more information about EMQX Docker please visit Docker Hub (opens new window) or Github (opens new window)

# Package Installation (Linux)

WARING

EMQX starts as emqx@127.0.0.1 by default and the node name will be written as a part of the builtin database. Purge database directory /var/lib/emqx/data/mnesia before starting it with a different name.

  1. Download EMQX package emqx.io (opens new window) or Github (opens new window)
  1. Install EMQX:

    • RPM package (RedHat/CentOS/RockyLinux/AmazonLinux):

      sudo yum install path/to/emqx-full-package-name.rpm
      
      1
    • DEB package (Ubuntu/Debian/Raspbian):

      sudo apt install path/to/emqx-full-package-name.deb
      
      1
  2. Start EMQX and check status

    • quick start

      sudo su - emqx
      emqx start
      emqx_ctl status
      
      1
      2
      3
    • systemctl

      sudo systemctl start emqx
      
      1
  3. Stop EMQX

    $ emqx stop
    
    1
  4. Uninstall EMQX

    • DEB:

      sudo apt remove --purge emqx
      
      1
    • RPM:

      sudo yum remove emqx
      
      1

# tgz (Linux, macOS, Windows)

WARING

tar.gz packages are released for quick testing and hot-beam upgrades. Do NOT install tar.gz packages for production unless you know how to manually resolve all the runtime dependencies.

WARING

The EMQX digital signature work on macOS has not been completed, and the installation and startup of the tgz package may be blocked by Gatekeeper (opens new window).

When you encounter a prompt like “erl” cannot be opened because the developer cannot be verified or “erlang_jq_port” cannot be opened because the developer cannot be verified at startup, solve this as follows:

Remove the extended attribute com.apple.quarantine of tgz file or folder:

xattr -d com.apple.quarantine emqx-full-package-name.tar.gz
# or
xattr -r -d com.apple.quarantine ./emqx
1
2
3

Please verify the SHA256 of the file when using this operation to ensure the integrity of the installation package, so as not to introduce additional security risks.

  1. Download EMQX package emqx.io (opens new window) or Github (opens new window)
  1. Extract the package:

    tar -zxf emqx-full-package-name.tar.gz
    
    1
  2. Start EMQX and check status

    ./bin/emqx start
    ./bin/emqx_ctl status
    
    1
    2
  3. Stop EMQX

    ./bin/emqx stop
    
    1
  4. Remove EMQX

    Simply delete the EMQX directory

# Install and cluster via Helm (K8S, K3S)

  1. Add helm repository
helm repo add emqx https://repos.emqx.io/charts
helm repo update
1
2
  1. Query EMQX
$ helm search repo emqx
NAME         CHART VERSION APP VERSION DESCRIPTION
emqx/emqx    v4.0.0        v4.0.0      A Helm chart for EMQX
emqx/emqx-ee v4.0.0        v4.0.0      A Helm chart for EMQX
emqx/kuiper  0.1.1         0.1.1       A lightweight IoT edge analytic software
1
2
3
4
5
  1. Start EMQX cluster
helm install my-emqx emqx/emqx
1
  1. View EMQX cluster situation
$ kubectl get pods
NAME       READY  STATUS             RESTARTS  AGE
my-emqx-0  1/1     Running   0          56s
my-emqx-1  1/1     Running   0          40s
my-emqx-2  1/1     Running   0          21s

$ kubectl exec -it my-emqx-0 -- emqx_ctl cluster status
Cluster status: #{running_nodes =>
                      ['my-emqx@my-emqx-0.my-emqx-headless.default.svc.cluster.local',
                       'my-emqx@my-emqx-1.my-emqx-headless.default.svc.cluster.local',
                       'my-emqx@my-emqx-2.my-emqx-headless.default.svc.cluster.local'],
                  stopped_nodes => []}
1
2
3
4
5
6
7
8
9
10
11
12

# Source code compilation and installation

  1. Get the source code
git clone https://github.com/emqx/emqx.git
1
  1. Checkout to latest tag
cd emqx
git checkout $(git describe --abbrev=0 --tags)
1
2
  1. Compile and run
make run
1