EMQX - MQTT broker (with SSL/TLS support for MQTTS and WSS)

[nktnet1]

Below are instructions for how to set up the EMQX broker in Dokploy with SSL/TLS, and with support for MQTTS and Websocket Secure.

Many steps will be similar to my instructions for encrypted Postgres.

Instructions

1. In your VPS (e.g. Hetzner), ensure that port 8883 (for MQTTS) and 443 (for WSS) are opened in the firewall

2. Edit /etc/dokploy/traefik/traefik.yml (you can do this in both CLI or Dokploy UI) to have the following entrypoints:

   entryPoints:
     web:
       address: ':80'
     websecure:
       address: ':443'
       http:
         tls:
           certResolver: letsencrypt
   
     # Add the lines below  <------------
     mqtts:
       address: ':8883'

3. On Dokploy, go to Web Server -> Traefik -> Additional Port Mapping and add the TCP mapping 8883:8883:

   

   Note that Traefik may be reloaded in this step which will result in downtime for a few seconds (if not, you will still need to reload Traefik manually).

4. Add a DNS entry for your domain/subdomain (e.g. an A record pointing to broker.yourdomain.com). If you're using Cloudflare, make sure to turn off proxy (i.e. DNS Only) if you want to use MQTT over TCP.

5. Create a Dokploy compose service with the following:

   services:
     # Broker and Dashboard:
     # - https://github.com/emqx/emqx
     emqx:
       image: emqx/emqx-enterprise:6.0.1
       hostname: node1.emqx.com
       environment:
         EMQX_NODE_NAME: emqx@node1.emqx.com
       expose:
         - 1883  # MQTT
         - 8083  # WS
         - 18083 # Dashboard
       volumes:
         - emqx_data:/opt/emqx/data
         - emqx_log:/opt/emqx/log
       networks:
         dokploy-network:
           aliases:
             - emqx-service
       labels:
         # MQTT over TLS from entrypoint mqtts (port 8883)
         - "traefik.tcp.routers.emqx-mqtts.entrypoints=mqtts"
         - "traefik.tcp.routers.emqx-mqtts.rule=HostSNI(`broker.yourdomain.com`)" # Change domain
         - "traefik.tcp.routers.emqx-mqtts.tls.certresolver=letsencrypt"
         - "traefik.tcp.routers.emqx-mqtts.service=emqx-service"
         - "traefik.tcp.services.emqx-service.loadbalancer.server.port=1883"
   
     #
     # Optional MQTT Web Client:
     # - https://github.com/emqx/MQTTX/tree/main/web
     #
     # mqttx-web:
     #   image: emqx/mqttx-web:latest
     #   expose:
     #     - 80
     #
   
   volumes:
     emqx_data:
     emqx_log:

   Make sure to change your domain (in both the labels above for MQTTS over TCP, as well as Dokploy domain settings for dashboard and WSS) as appropriate.

   Personally, I've set the EMQX dashboard to emqx.yourdomain.com, the MQTTX client on mqttx.yourdomain.com, and the broker on broker.yourdomain.com.

   The dashboard and web client can have Cloudflare proxy enabled, but not the broker (for TCP connections). If you're using websocket connections only, then it doesn't matter. You could even introduce a wss-broker.yourdomain.com with proxy on if you wish.

   The initial dashboard credentials are:

   USERNAME: admin
   PASSWORD: public
   

6. For clients to connect, you will need to create client credentials in the EMQX dashboard at emqx.yourdomain.com:

   

   (click "users", then "add")

   

   Then simply connect to broker.yourdomain.com at either port 8883 (for TCP) or 443 (for WebSocket) with your user credentials.

---

Template Pull Request:

• feat: emqx template (MQTT Broker) templates#556

[Serhioromano]

Are you sure with post numbers? I cannot connect. Als I had to add.

networks:
  dokploy-network:
    external: true

Because I had an error that dokploy-network does not exists,

Also Are ports ok? On you imaged in traefik yaml and traefik config you use 8883. Abd in traefik lables 1883. I cannot if I use remote client I cannot connect. I use dokploy IP or domain nothing seams to work.

[Serhioromano]

How do I do that? Add another domain or lable to compose?

[nktnet1]

From the Dokploy screenshot, click the "Add Domain" button (in white) at the top-right corner, choose a domain (e.g. broker.yourdomain.com), port 8083, EMQX container.

P.s. I forgot EMQX uses port 8083 (not 80) for Web Socket - have fixed it in the above messages.

[Serhioromano]

I still cannot get it. I added this domain.

What port should I use now in wss:// connection? 443 or 8083? Anyway either one of those does not work. I disabled UFW so it should not be an issue. I try to connect like this.

[nktnet1]

You need to use port 443, since WSS operates on the same port as HTTPS.
8883 only is the internal port for the EMQX container - i.e. not public-facing.

Your path also needs to be /mqtt, not /. Read this guide: https://www.emqx.com/en/blog/connect-to-mqtt-broker-with-websocket

Also, is the domain pointing to your server in your DNS settings?

Try stopping and restarting the EMQX container as well, otherwise Dokploy will not issue your certificate.

Finally, what error message are you getting? If the MQTTX client isn't showing the error clearly and you have an Android device, you can try using my application here just to test the connection and see issues in the debug log.

[Serhioromano]

I give up.

[Shiba-Kar]

@nktnet1 What I am missing here , Using the latest Dokploy. Cant Connect using the mqttx-web .

# This templates requires additional traefik port mapping and entry point
# for port 8883 (mqtts over TCP)
#
# For the full instructions, refer to:
# - https://github.com/Dokploy/dokploy/discussions/3126
#
# The initial login credentials are:
# - USERNAME: admin
# - PASSWORD: public

services:
  emqx:
    image: emqx/emqx-enterprise:latest
    hostname: node1.emqx.com
    environment:
      EMQX_NODE_NAME: emqx@node1.emqx.com
    expose:
      - 1883  # MQTT
      - 8083  # WS
      - 18083 # Dashboard
    volumes:
      - emqx_data:/opt/emqx/data
      - emqx_log:/opt/emqx/log
    networks:
      dokploy-network:
        aliases:
          - emqx-service
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "/opt/emqx/bin/emqx_ctl", "status"]
      interval: 30s
      timeout: 5s
      retries: 3
    labels:
      # MQTT over TLS
      - "traefik.tcp.routers.emqx-mqtts.entrypoints=mqtts"
      - "traefik.tcp.routers.emqx-mqtts.rule=HostSNI(`broker.mqtt.xxxx.com`)" # Change domain
      - "traefik.tcp.routers.emqx-mqtts.tls.certresolver=letsencrypt"
      - "traefik.tcp.routers.emqx-mqtts.service=emqx-service"
      - "traefik.tcp.services.emqx-service.loadbalancer.server.port=1883"

  #
  # Optional Web UI:
  # - https://github.com/emqx/MQTTX/tree/main/web
  #
  mqttx-web:
    image: emqx/mqttx-web:latest
    expose:
      - 80
  #

volumes:
  emqx_data:
  emqx_log:

networks:
  dokploy-network:
    external: true

global:
  sendAnonymousUsage: false
providers:
  swarm:
    exposedByDefault: false
    watch: true
  docker:
    exposedByDefault: false
    watch: true
    network: dokploy-network
  file:
    directory: /etc/dokploy/traefik/dynamic
    watch: true
entryPoints:
  web:
    address: :80
  websecure:
    address: :443
    http3:
      advertisedPort: 443
    http:
      tls:
        certResolver: letsencrypt
  mqtts:
    address: :8883       
api:
  insecure: true
certificatesResolvers:
  letsencrypt:
    acme:
      email: xxxxxxxxxxx@gmail.com
      storage: /etc/dokploy/traefik/dynamic/acme.json
      httpChallenge:
        entryPoint: web
accessLog:
  filePath: /etc/dokploy/traefik/dynamic/access.log
  format: json
  bufferingSize: 100

[Shiba-Kar]

Yes I can connect now . https://www.emqx.com/en/blog/esp8266-connects-to-the-public-mqtt-broker#connecting-esp8266-to-an-mqtt-broker . But now how can I connect the esp8266 securely to the broker .

[nktnet1]

What do you mean by "securely"?

If you're using port 443 from following my guide, it's WSS (WebSocket Secure).

If you use port 8883, it's MQTTS (S = secure).

You can see in Webview Kiosk that there's a "Use TLS" option, which you have already enabled.

---

As for esp8266, that's outside the scope for me. I suggest searching on EMQX's discussion:

• https://github.com/emqx/emqx/discussions

and if there's no-one with a similar issue to you, consider creating a new post.

[Shiba-Kar]

Now the WebSocket works fine . For TCP i used 8883 in Webview Kiosk and changed WebSocket to false. The connection timeout , domain is broker.mqtt.xxxxxx.com .

[nktnet1]

Can you attach the debug logs of Webview Kiosk?

Also, which hosting provider are you using? In your VPS, check whether you're using UFW or if your provider has a built in firewall. You need to allow TCP traffic on port 8883.

[Shiba-Kar]

All works fine now I have misconfigured the firewall. @nktnet1 Thanks a lot .