hivemq/hivemq4 repository overview

⁠Quick Reference

• Where to get help: Contact⁠

• Maintained by: HiveMQ⁠

⁠What is HiveMQ?

HiveMQ is a MQTT based messaging platform designed for the fast, efficient and reliable movement of data to and from connected IoT devices. It uses the MQTT protocol for instant, bi-directional push of data between your device and your enterprise systems. HiveMQ is built to address some of the key technical challenges organizations face when building new IoT applications, including:

• Building reliable and scalable business critical IoT applications
• Fast data delivery to meet the expectations of end users for responsive IoT products
• Lower cost of operation through efficient use of hardware, network and cloud resources
• Integrating IoT data into existing enterprise systems

While at its core, HiveMQ is an MQTT 3.1, MQTT 3.1.1 and MQTT 5.0 compliant MQTT broker, HiveMQ excels with its additional features designed for enterprise use cases and professional deployments.

See HiveMQ MQTT Broker⁠ for more information.

⁠Tags

WARNING: The legacy HiveMQ Operator and its Helm chart have been retired since April 2025 and no longer receive updates or support. The last HiveMQ Platform version compatible with the legacy operator is k8s-4.47.0. To migrate to the current HiveMQ Platform Operator for Kubernetes, see HiveMQ Legacy Operator to Platform Operator Migration Guide⁠.

⁠Basic Single Instance

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

docker run --ulimit nofile=500000:500000 -p 8080:8080 -p 8000:8000 -p 1883:1883 hivemq/hivemq4

You can connect to the broker via MQTT (1883) or Websockets (8000) or the Control Center (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 Extension⁠ built in. It can be used with any container orchestration engine that supports service discovery using a round-robin A record.

A custom solution supplying the A record could be used as well.

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

Following are two examples, describing how to use this image on Docker Swarm and Kubernetes respectively.

Other environments are compatible as well (provided they support DNS discovery in some way).

⁠Local Cluster with Docker Swarm

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

Note: 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/hivemq4:dns-latest

This will provide a 3 node cluster with the MQTT (1883) and HiveMQ Control Center (8080) ports forwarded to the host network.

This means you can connect MQTT clients on port 1883. The connection will be forwarded to any of the cluster nodes.

For more information, see managing the cluster⁠.

⁠Production Use with Kubernetes

Please consider using the HiveMQ Platform Operator for Kubernetes⁠ to deploy a HiveMQ Platform in Kubernetes.

⁠Accessing the HiveMQ Control Center

To access the HiveMQ HiveMQ Control Center for a cluster running on Kubernetes, follow these steps:

• Create a service exposing the HiveMQ Control Center of the HiveMQ service. Use the following YAML definition (as web.yaml):

kind: Service
apiVersion: v1
metadata:
  name: hivemq-control-center
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: Depending on your provider of Kubernetes environment, load balancers might not be available or additional configuration may be necessary to access the HiveMQ Control Center.

⁠Accessing the MQTT Port Using External Clients

To allow access for the MQTT port of a cluster running on Kubernetes, follow these steps:

• 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

Note: The externalTrafficPolicy annotation is necessary to allow the Kubernetes service to maintain a larger amount of concurrent connections.
See Source IP for Services⁠ for more information.

⁠Configuration

⁠Setting the HiveMQ Control Center Username and Password

The environment variable HIVEMQ_CONTROL_CENTER_PASSWORD allows you to set the password of the HiveMQ Control Center by defining a SHA256 hash for a custom password.

Additionally, you can also configure the username, using the environment variable HIVEMQ_CONTROL_CENTER_USER.

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

⁠Adding a License

To use a license with a HiveMQ docker container, 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.

⁠Disabling the hivemq-allow-all-extension

By default the HiveMQ docker images use the packaged hivemq-allow-all-extension.

This can be circumvented by setting the HIVEMQ_ALLOW_ALL_CLIENTS environment variable to false.

This will cause the entrypoint script to delete the extension on startup.

⁠Disabling Privilege Step-Down

By default the HiveMQ docker images check for root privileges at startup and, if present, switch to a less privileged user before running the HiveMQ broker.

This will enhance the security of the container.

If you wish to skip this step, set the environment variable HIVEMQ_NO_ROOT_STEP_DOWN to false.

⁠Overriding the Cluster Bind Address

By default the HiveMQ DNS discovery image attempts 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.

⁠Setting the Cluster Transport Type

By default the HiveMQ DNS discovery image uses UDP as transport protocol for the cluster transport.

If you would like to use TCP as transport type instead, you can set the HIVEMQ_CLUSTER_TRANSPORT_TYPE environment variable to TCP.

Note: We generally recommend using TCP for the cluster transport, as it makes HiveMQ less susceptible to network splits under high network load.

⁠Building a custom Docker image

See our documentation⁠ for more information on how to build custom HiveMQ images.