Self-host EMQX with Levelrail

A scalable MQTT broker for IoT and smart home devices with a web dashboard.

  • Authoremqx
  • LicenceBUSL-1.1
  • Memory1 GiB
  • Services1

How to self-host EMQX

  1. Pull the images

    One image is pulled on your server.

    Show images
    • emqx/emqx:6.3.2
  2. Create the app

    One service starts in a single Compose app, with 2 named volume mounts for your data, on ports 18083, 1883.

  3. Fill in the secrets

    1 secret is generated and stored encrypted, you do not have to fill in anything.

  4. Open it

    Without a domain the app gets an sslip.io address; add --domain SERVICE=HOST to use your own.

After the first start

  • Sign in as admin with the generated password. Devices reach the broker at emqx:1883 inside the project network.

EMQX requirements

Memory
About 1 GiB
Architectures
amd64 unknown, arm64 unknown
Ports
18083, 1883
Domain
Optional, an sslip.io address is used without one
Settings
none to fill in
License
BUSL-1.1, source available
  • Listed. It is in the catalog but not verified. Back up the data volume before changing an image tag.

Install Levelrail first

On a server with Levelrail running, run the command above, or open the dashboard: Apps, New app, Browse templates, then EMQX. New to Levelrail? Install it on a fresh VPS first.

docker pull ghcr.io/glincker/levelrail:latest

Then levelrail-cli login --device. See Getting started and the EMQX docs page.

Deploy EMQX your way

Every format below deploys the same pinned images. Pick the one that fits how you work.

Deploy EMQX from the CLI

Add --domain SERVICE=HOST to serve a service on your own domain, for example --domain emqx=app.example.com.

levelrail-cli templates install emqx --name my-emqx

Deploy EMQX with the API

Create a token in the dashboard first. Name, env and domains are the request fields.

curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  https://levelrail.example.com/api/v1/service-templates/emqx/install \
  -d '{
    "name": "my-emqx"
  }'

EMQX configuration

EMQX services

ServiceImagePortsVolumes
emqx emqx/emqx:6.3.2 18083, 1883 data -> /opt/emqx/datalog -> /opt/emqx/log

EMQX environment variables

VariableServiceValue
EMQX_DASHBOARD__DEFAULT_PASSWORD emqx Generated at deploy

Ports and volumes

Ports
18083, 1883
Volumes
2 named mounts: data -> /opt/emqx/data, log -> /opt/emqx/log

EMQX FAQ

How much memory does EMQX need?

The catalog lists about 1 GiB of memory for EMQX.

Does EMQX run on arm64?

For EMQX, arm64 support is not confirmed; amd64 is unknown.

What licence is EMQX under?

EMQX is licensed under BUSL-1.1, which is source-available, so read the terms before commercial use.

Does EMQX need configuration before it starts?

No. The template fills in its own defaults and generates secrets at deploy time.

Which ports does EMQX use?

EMQX listens on ports 18083 and 1883 inside the stack.

Where does EMQX keep its data?

In named volumes: data mounted at /opt/emqx/data and log mounted at /opt/emqx/log.

Can I deploy EMQX on Dokploy or Dokku?

The services and pinned images on this page can be run on any Docker host. The public Dokploy templates list has an entry with the id emqx for this app, so check that entry as well. Dokku deploys container images with its own commands, so the pinned image emqx/emqx:6.3.2 is what you deploy there.

levelrail-cli templates install emqx --name my-emqx