Deploy EMQX on a VPS

EMQX is a high-performance MQTT broker used for IoT / pub-sub messaging. This guide covers a production-ready single-node install on Ubuntu 22.04/24.04 (Debian 11/12 notes included).

1. Prerequisites

• A RamNode KVM VPS — 1 vCPU / 1–2 GB RAM is enough for testing; 2 vCPU / 4 GB+ for production with many clients.
• Ubuntu 22.04/24.04 or Debian 11/12, fully updated.
• A domain name (optional but recommended) pointed at your VPS's IP if you want TLS with a real certificate.
• Root or sudo access.

sudo apt update && sudo apt upgrade -y

2. Install EMQX

Option A — APT repository (recommended)

curl -s https://assets.emqx.com/scripts/install-emqx-deb.sh | sudo bash
sudo apt install -y emqx

Option B — Docker (good if you want isolation/easy upgrades)

sudo apt install -y docker.io docker-compose-plugin
sudo docker run -d --name emqx \
  -p 1883:1883 -p 8083:8083 -p 8084:8084 \
  -p 8883:8883 -p 18083:18083 \
  -v emqx-data:/opt/emqx/data \
  -v emqx-log:/opt/emqx/log \
  emqx/emqx:latest

The rest of this guide assumes Option A (native package), but the same config paths apply inside the container under /opt/emqx/etc/.

3. Start and enable the service

sudo systemctl enable --now emqx
sudo systemctl status emqx

Default ports:

4. Configure the firewall

sudo ufw allow 1883/tcp
sudo ufw allow 8883/tcp
sudo ufw allow 8083/tcp
sudo ufw allow 8084/tcp
sudo ufw allow 18083/tcp   # dashboard — consider restricting to your IP
sudo ufw enable
sudo ufw status

If using RamNode's cloud firewall / security groups instead of (or in addition to) ufw, open the same ports there.

Recommendation: restrict 18083 (dashboard) to your own IP or put it behind a reverse proxy with auth, since it's exposed to the internet by default.

5. Access the Dashboard

Browse to http://YOUR_VPS_IP:18083

Default login:

• Username: admin
• Password: public

Change this immediately under Dashboard → System → Users, or via CLI:

sudo emqx ctl admins passwd admin '<new-strong-password>'

6. Enable TLS with Let's Encrypt (recommended for production)

Install certbot and get a certificate (standalone, so temporarily stop anything on port 80):

sudo apt install -y certbot
sudo certbot certonly --standalone -d mqtt.yourdomain.com

Point EMQX at the certs. Edit /etc/emqx/emqx.conf and add/adjust:

listeners.ssl.default {
  bind = "0.0.0.0:8883"
  ssl_options {
    certfile = "/etc/letsencrypt/live/mqtt.yourdomain.com/fullchain.pem"
    keyfile  = "/etc/letsencrypt/live/mqtt.yourdomain.com/privkey.pem"
  }
}

listeners.wss.default {
  bind = "0.0.0.0:8084"
  ssl_options {
    certfile = "/etc/letsencrypt/live/mqtt.yourdomain.com/fullchain.pem"
    keyfile  = "/etc/letsencrypt/live/mqtt.yourdomain.com/privkey.pem"
  }
}

Restart EMQX:

sudo systemctl restart emqx

Set up auto-renewal (certbot installs a systemd timer by default — verify with systemctl list-timers | grep certbot), and add a renewal hook to restart EMQX:

echo '#!/bin/bash
systemctl restart emqx' | sudo tee /etc/letsencrypt/renewal-hooks/deploy/emqx-restart.sh
sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/emqx-restart.sh

7. Basic authentication (optional but recommended)

By default EMQX allows anonymous connections. To require credentials:

1. In the Dashboard, go to Access Control → Authentication.
2. Add a "Password-Based" authenticator (built-in database is simplest).
3. Add users under Users.
4. Under Settings → Access Control, disable "Allow Anonymous".

Or via CLI:

sudo emqx ctl authz cache-clean

(For durable config, prefer the Dashboard or emqx.conf — CLI auth config is limited in newer EMQX versions.)

8. Test the broker

Install an MQTT client:

sudo apt install -y mosquitto-clients

Subscribe:

mosquitto_sub -h localhost -t "test/topic" -v

Publish (in another shell/session):

mosquitto_pub -h localhost -t "test/topic" -m "hello from emqx"

You should see the message appear in the subscriber terminal.

9. Verify and monitor

sudo emqx ctl status
sudo emqx ctl listeners
sudo journalctl -u emqx -f

The Dashboard also shows live connections, topics, and throughput under Monitoring.

10. Common troubleshooting

11. Next steps

• Set up clustering (multiple EMQX nodes) once you outgrow a single VPS.
• Integrate rule engine → forward messages to Kafka, Postgres, webhooks, etc.
• Set up backups of /etc/emqx and /var/lib/emqx (or the Docker volumes).