Connecting HighByte to HiveMQ Using Non-TLS and TLS Listeners

This guide explains the process of connecting HighByte Intelligence Hub to the HiveMQ MQTT broker using both non-secure (non-TLS) and secure (TLS) connections. This setup is useful when integrating industrial data pipelines where MQTT is used for communication.

✅ Prerequisites

• Docker is installed on your system

• TLS certificates (This guide uses self-signed certificates — refer to our HowTos documentation for certificate generation steps)

• A shared Docker network named mqtt_network to allow communication between HighByte and HiveMQ containers. If the shared network doesn't exist yet, you can create it with the following command:

  docker network create mqtt_network

 Instructions

1. Installing HighByte Intelligence Hub Using Docker: (You can skip the following steps if Highbyte is already installed)

   1. We are installing Highbyte using a Docker image. Followed the official documentation of Highbyte.
      Run the following Docker command to load the Docker image:

      docker load -i "HighByte-Intelligence-Hub-4.1.2_Docker_Build-2025.4.22.2.tar"

   2. Create a Docker Compose file for HighByte (docker-compose.highbyte.yml):

      docker network create mqtt_network
      version: '3.8' services: highbyte: image: highbyte:4.1.2 container_name: highbyte-hub ports: - "45245:45245" - "1885:1885" - "8885:8885" volumes: - highbyte-data:/app/data networks: - mqtt_network restart: unless-stopped volumes: highbyte-data: networks: mqtt_network: external: true

   3. Deploy HighByte using Docker Compose:

      Run the following command to start HighByte:

      docker-compose -f docker-compose.highbyte.yml up -d

   4. Verify that HighByte started successfully:

      Check the logs to ensure HighByte is running:

      docker logs highbyte-hub

   5. You should see messages indicating that HighByte has started successfully, such as:

      INFO | Runtime | Starting configuration services on http://0.0.0.0:45245/. INFO | Runtime | Started runtime.

      Now, access the HighByte web UI by navigating to http://localhost:45245.

2. Installing HiveMQ with Non-TLS and TLS Listeners

   1. Configure config.xml for HiveMQ.

      This configuration enables both the non-TLS and TLS MQTT listeners on ports 1883 and 8883, respectively.

      <?xml version="1.0" encoding="UTF-8" ?> <hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="config.xsd"> <listeners> <tcp-listener> <port>1883</port> <bind-address>0.0.0.0</bind-address> </tcp-listener> <tls-tcp-listener> <port>8883</port> <bind-address>0.0.0.0</bind-address> <tls> <keystore> <path>certs/hivemq.jks</path> <password>*****</password> <private-key-password>*****</private-key-password> </keystore> <client-authentication-mode>REQUIRED</client-authentication-mode> <truststore> <path>certs/hivemq-trust-store.jks</path> <password>*****</password> </truststore> </tls> </tls-tcp-listener> </listeners> <anonymous-usage-statistics> <enabled>true</enabled> </anonymous-usage-statistics> </hivemq>

   2. Directory structure for Config.xml and HiveMQ Certs
      
      

      Open

      

   3. Create a Docker Compose file for HiveMQ (docker-compose.hivemq.yml):

      version: '3.8' services: hivemq: image: hivemq/hivemq4 container_name: hivemq ports: - "1883:1883" - "8883:8883" volumes: - ./config:/opt/hivemq/conf - ./certs:/opt/hivemq/certs networks: - mqtt_network restart: unless-stopped networks: mqtt_network: external: true

   4. Run the following command to start HiveMQ:

      docker-compose -f docker-compose.hivemq.yml up -d

   5. Check the logs to confirm HiveMQ started successfully:

      docker logs hivemq

      Ensure that both ports 1883 and 8883 are open and listening for connections.

3. Now that both HiveMQ and HighByte are running, it's time to configure the connection between HighByte and HiveMQ.

   1. Connecting to Non-TLS Listener (Port 1883)

      1. Open the HighByte web UI.

      2. Create a new MQTT connection.

      3. Set the broker host to hivemq container name (or the IP address of the HiveMQ container).

      4. Use port 1883 for the connection.

      5. Do not enable SSL for this connection. No certificates are required for this non-TLS connection.

      6. Save the connection.

      7. Test connection using UNS Client.

      8. Open

         

          

   2. Connecting to TLS Listener (Port 8883)

      1. Open the HighByte web UI.

      2. Navigate to Settings → Certificates

      3. Add HiveMQ Broker CA server certificate and Client public and private key.
         
         

         Open

         

      4. Create a new MQTT connection.

      5. Set the broker host to hivemq container name (or the IP address of the HiveMQ container).

      6. Use port 8883 for the connection.

      7. Enable SSL/TLS for this connection.

      8. Select the Server CA and Client cert

      9. Save the connection.
         
         

         Open

         

Notes

1. You can use a combined Docker Compose file for both HiveMQ and HighByte if desired.

2. If you encounter issues with connecting, try using MQTT CLI or MQTT Explorer to test your certificates. This can help identify certificate-related issues before troubleshooting the connection.

3. Be sure to use unencrypted private keys when uploading them to HighByte. If your client’s private key is encrypted, you must decrypt it before uploading it to HighByte. Use the following OpenSSL command to decrypt the key:

   openssl rsa -in mqtt-client-key.pem -out mqtt-client-private-key.pem

   After uploading the certificates and configuring SSL/TLS, HighByte should be able to connect securely to HiveMQ.

 Related articles