hivemq/hivemq3 repository overview

⁠Quick Reference

• Where to get help: Contact⁠

• Where to file issues: GitHub issue tracker⁠

• Maintained by: HiveMQ ⁠

• Dockerfiles: GitHub⁠

⁠What is HiveMQ?

HiveMQ is an MQTT broker designed for mission-critical enterprise scenarios.

While at its core, HiveMQ is an MQTT 3.1 and MQTT 3.1.1 compatible MQTT broker, HiveMQ excels with its additional features.

Besides the stellar performance, HiveMQ is the leading innovator among MQTT brokers and is improving businesses that rely on MQTT day-to-day.

See Features⁠ for more information.

⁠Tags

⁠Basic single instance

To start a single HiveMQ instance and allow access to the MQTT port as well as the Web UI, get Docker⁠ and run the following command:

docker run -p 8080:8080 -p 1883:1883 hivemq/hivemq3

You now have a dockerized local HiveMQ and can connect to the broker (1883) or the WebUI (8080) via the respective ports.

⁠Clustering

For running HiveMQ in a cluster, we recommend using the DNS-discovery image. This image has the HiveMQ DNS Discovery Plugin⁠ built in. It can be used with any container orchestration engine that supports service discovery using a round-robin A record.

The following environment variables can be used to customize the discovery and broker configuration respectively.

⁠Run a cluster locally

To start a HiveMQ cluster locally, you can use Docker Swarm.

Please note that using Docker Swarm in production is not recommended.

• Start a single node Swarm cluster by running:

docker swarm init

• Create an overlay network for the cluster nodes to communicate on:

docker network create -d overlay --attachable myNetwork

• Create the HiveMQ service on the network

docker service create \
  --replicas 3 --network myNetwork \
  --env HIVEMQ_DNS_DISCOVERY_ADDRESS=tasks.hivemq \
  --publish target=1883,published=1883 \
  --publish target=8080,published=8080 \
  -p 8000:8000/udp \
  --name hivemq \
    hivemq/hivemq3:dns-latest

This will provide a 3 node cluster with MQTT port and web UI forwarded to the host network.

For more information, see managing the cluster⁠.

⁠Production use

For production we recommend using the DNS discovery image in combination with Kubernetes.

On Kubernetes, an appropriate deployment configuration is necessary to utilize DNS discovery. A headless service⁠ will provide a DNS record for the broker that can be used for discovery.

Following is an example configuration for a HiveMQ cluster with 3 nodes using DNS discovery in a replication controller setup.

Please note that you may have to replace HIVEMQ_DNS_DISCOVERY_ADDRESS according to your Kubernetes namespace and configured domain.

apiVersion: v1
kind: ReplicationController
metadata:
  name: hivemq-replica
spec:
  replicas: 3
  selector:
    app: hivemq-cluster1
  template:
    metadata:
      name: hivemq-cluster1
      labels:
        app: hivemq-cluster1
    spec:
      containers:
      - name: hivemq-pods
        image: hivemq/hivemq3:dns-latest
        ports:
        - containerPort: 8080
          protocol: TCP
          name: web-ui
        - containerPort: 1883
          protocol: TCP
          name: mqtt
        env:
        - name: HIVEMQ_DNS_DISCOVERY_ADDRESS
          value: "hivemq-discovery.default.svc.cluster.local."
        - name: HIVEMQ_DNS_DISCOVERY_TIMEOUT
          value: "20"
        - name: HIVEMQ_DNS_DISCOVERY_INTERVAL
          value: "21"
        readinessProbe:
          tcpSocket:
            port: 1883
          initialDelaySeconds: 30
          periodSeconds: 60
          failureThreshold: 60
        livenessProbe:
          tcpSocket:
            port: 1883
          initialDelaySeconds: 30
          periodSeconds: 60
          failureThreshold: 60
---
kind: Service
apiVersion: v1
metadata:
  name: hivemq-discovery
  annotations:
    service.alpha.kubernetes.io/tolerate-unready-endpoints: "true"
spec:
  selector:
    app: hivemq-cluster1
  ports:
    - protocol: TCP
      port: 1883
      targetPort: 1883
  clusterIP: None

⁠Accessing the Web UI

To access the HiveMQ Web UI for a cluster running on Kubernetes, create a service exposing the Web UI of the HiveMQ service. Use the following YAML definition (as web.yaml):

kind: Service
apiVersion: v1
metadata:
  name: hivemq-web-ui
spec:
  selector:
    app: hivemq-cluster1
  ports:
    - protocol: TCP
      port: 8080
      targetPort: 8080
  sessionAffinity: ClientIP
  type: LoadBalancer

Create the service using kubectl create -f web.yaml

Note that depending on your provider of Kubernetes environment, load balancers might not be available or additional configuration may be necessary to access the Web UI.

⁠Accessing the MQTT port using external clients

To allow access for the MQTT port of a cluster running on Kubernetes, create a service exposing the MQTT port using a load balancer. You can use the following YAML definition (as mqtt.yaml):

kind: Service
apiVersion: v1
metadata:
  name: hivemq-mqtt
  annotations:
    service.spec.externalTrafficPolicy: Local
spec:
  selector:
    app: hivemq-cluster1
  ports:
    - protocol: TCP
      port: 1883
      targetPort: 1883
  type: LoadBalancer

Create the service using kubectl create -f mqtt.yaml

⁠Setting the Web UI username and password

The environment variable HIVEMQ_WEB_UI_PASSWORD allows you to set the password of the Web UI by defining a SHA256 hash for a custom password. Additionally, you can also configure the username, using the environment variable HIVEMQ_WEB_UI_USER

See Generate a SHA256 Password⁠ to read more about how to generate the password hash.

⁠Adding a license

To use a license with this image, you must first encode it as a string.

To do so, run cat license.lic | base64 (replace license.lic with the path to your license file).

Set the resulting string as the value for the HIVEMQ_LICENSE environment variable of the container.

⁠Overriding the bind address

By default this image will attempt to set the bind address using the containers ${HOSTNAME} to ensure that HiveMQ will bind the cluster connection to the correct interface so a cluster can be formed.

This behavior can be overridden by setting any value for the environment variable HIVEMQ_BIND_ADDRESS. The broker will attempt to use the given value as the bind address instead.