# Installation

EMQX binary packages are released on below operating systems:

CentOS 7 (EL7)
CentOS 8 (EL8)
Raspbian 10
Debian 9
Debian 10
Ubuntu 16.04
Ubuntu 18.04
Ubuntu 20.04
macOS 10
Windows Server 2019

# Package Installation (Linux)

Download EMQX package emqx.com (opens new window) or Github (opens new window)

Install EMQX Broker:

RPM package:

$ sudo yum install emqx-cenots7-v4.0.0.x86_64.rpm

DEB package:

# for ubuntu/debian
$ sudo apt install ./emqx-ubuntu18.04-v4.0.0_amd64.deb
$ sudo apt install ./emqx-debian10-v4.0.0_amd64.deb

1
2
3

Start EMQX Broker

quick start

$ emqx start
emqx 4.0.0 is started successfully!
$ emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running

1
2
3
4
5

systemctl
```
$ sudo systemctl start emqx
```
1
start as service
```
$ sudo service emqx start
```
1

Stop EMQX Broker
```
$ emqx stop
ok
```
1
2

Uninstall EMQX Broker

DEB:
```
$ sudo apt remove --purge emqx
```
1
RPM:
```
$ sudo yum remove emqx
```
1

# ZIP (Linux、MacOS、Windows)

::: ZIP packages are released for quick testing and hot-beam upgrade. Do NOT install zip packages for production unless you know how to manually resolve all the runtime dependencies. :::

Download EMQX zip package from emqx.com (opens new window) or Github (opens new window).
Unzip the installation file:
```
$ unzip emqx-ubuntu18.04-v4.0.0.zip
```
1

Start EMQX Broker

$ ./bin/emqx start
emqx 4.0.0 is started successfully!

$ ./bin/emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx v4.0.0 is running

1
2
3
4
5
6

Stop EMQX Broker
```
$ ./bin/emqx stop
ok
```
1
2
Remove EMQX Broker
Simply delete the EMQX Broker directory

# Running EMQX in Docker (Contain a simple docker-compose cluster)

# Run a single container

Get docker image
- From Docker Hub (opens new window)
```
$ docker pull emqx/emqx:v4.0.0
```
  1

Start docker container

$ docker run -d --name emqx -p 1883:1883 -p 8081:8081 -p 8083:8083 -p 8883:8883 -p 8084:8084 -p 18083:18083 emqx/emqx:v4.0.0

# Create a simple static cluster by docker-compose

Create docker-compose.yaml file

version: '3'

services:
  emqx1:
    image: emqx/emqx:v4.0.0
    environment:
    - "EMQX_NAME=emqx"
    - "EMQX_HOST=node1.emqx.io"
    - "EMQX_CLUSTER__DISCOVERY=static"
    - "EMQX_CLUSTER__STATIC__SEEDS=emqx@node1.emqx.io, emqx@node2.emqx.io"
    - "EMQX_ZONE__EXTERNAL__RETRY_INTERVAL=2s"
    - "EMQX_MQTT__MAX_TOPIC_ALIAS=10"
    volumes:
        - ./tmp/emqx.lic:/opt/emqx/etc/emqx.lic
    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:v4.0.0
    environment:
    - "EMQX_NAME=emqx"
    - "EMQX_HOST=node2.emqx.io"
    - "EMQX_CLUSTER__DISCOVERY=static"
    - "EMQX_CLUSTER__STATIC__SEEDS=emqx@node1.emqx.io, emqx@node2.emqx.io"
    - "EMQX_ZONE__EXTERNAL__RETRY_INTERVAL=2s"
    - "EMQX_MQTT__MAX_TOPIC_ALIAS=10"
    volumes:
        - ./tmp/emqx.lic:/opt/emqx/etc/emqx.lic
    healthcheck:
      test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
      interval: 5s
      timeout: 25s
      retries: 5
    networks:
      emqx-bridge:
        aliases:
        - node2.emqx.io

  client:
    image: python:3.7.2-alpine3.9
    depends_on:
      - emqx1
      - emqx2
    tty: true
    networks:
        emqx-bridge:

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
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58

Start docker-compose cluster
```
$ docker-compose -p my_emqx up -d
```
1

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 Broker Docker, please visit Docker Hub (opens new window) or Github (opens new window)

# Source code compilation and installation

Get the source code

$ git clone https://github.com/emqx/emqx.git

Checkout to latest tag

$ cd emqx
$ git checkout $(git describe --abbrev=0 --tags)

1
2

Compile

$ make

Start EMQX Broker

$ cd _build/emqx/rel/emqx

$ ./bin/emqx start
EMQX Broker 4.3-beta.1 is started successfully!

$ ./bin/emqx_ctl status
Node 'emqx@127.0.0.1' is started
emqx 4.3-beta.1 is running

1
2
3
4
5
6
7
8

← Getting Started EMQX on Kubernetes (opens new window) →