{"id":13587872,"url":"https://github.com/hivemq/hivemq4-docker-images","last_synced_at":"2025-04-16T07:33:05.841Z","repository":{"id":33965775,"uuid":"160503603","full_name":"hivemq/hivemq4-docker-images","owner":"hivemq","description":"Official Docker Images for the Enterprise MQTT Broker HiveMQ","archived":false,"fork":false,"pushed_at":"2024-05-13T13:14:38.000Z","size":133,"stargazers_count":19,"open_issues_count":2,"forks_count":12,"subscribers_count":18,"default_branch":"master","last_synced_at":"2024-05-14T11:55:53.563Z","etag":null,"topics":["cloud-native","cluster","docker","docker-image","docker-swarm","hivemq","kubernetes","mqtt","mqtt-broker","mqtt-server","mqtt5"],"latest_commit_sha":null,"homepage":"https://www.hivemq.com","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hivemq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-12-05T10:47:52.000Z","updated_at":"2024-08-27T09:40:09.465Z","dependencies_parsed_at":"2024-02-05T15:57:35.469Z","dependency_job_id":"4991a5de-dda3-415e-bcca-0299da427ff0","html_url":"https://github.com/hivemq/hivemq4-docker-images","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivemq%2Fhivemq4-docker-images","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivemq%2Fhivemq4-docker-images/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivemq%2Fhivemq4-docker-images/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hivemq%2Fhivemq4-docker-images/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hivemq","download_url":"https://codeload.github.com/hivemq/hivemq4-docker-images/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249213734,"owners_count":21231096,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-native","cluster","docker","docker-image","docker-swarm","hivemq","kubernetes","mqtt","mqtt-broker","mqtt-server","mqtt5"],"created_at":"2024-08-01T15:06:24.024Z","updated_at":"2025-04-16T07:33:05.832Z","avatar_url":"https://github.com/hivemq.png","language":"Shell","funding_links":[],"categories":["Shell"],"sub_categories":[],"readme":"\u003e [!IMPORTANT]\n\u003e We are now using the [Gradle OCI Plugin](https://github.com/SgtSilvio/gradle-oci) to buid all of our OCI images.\n\n# Table of Contents\n   \n* [What is HiveMQ?](#what-is-hivemq)\n* [HiveMQ Docker Images](#hivemq-docker-images)\n  * [HiveMQ Base Image](#hivemq-base-image)\n  * [HiveMQ DNS Discovery Image](#hivemq-dns-discovery-image)\n  * [Tags](#tags)\n* [Basic Single Instance](#basic-single-instance)\n* [Clustering](#clustering)\n  * [Local Cluster with Docker Swarm](#local-cluster-with-docker-swarm)\n    * [Managing the Cluster](#managing-the-cluster)\n  * [Production Use with Kubernetes](#production-use-with-kubernetes)\n    * [Accessing the HiveMQ Control Center](#accessing-the-hivemq-control-center)\n    * [Accessing the MQTT Port Using External Clients](#accessing-the-mqtt-port-using-external-clients)\n* [Configuration](#configuration)\n  * [Setting the HiveMQ Control Center Username and Password](#setting-the-hivemq-control-center-username-and-password)\n  * [Adding a License](#adding-a-license)\n  * [Disabling the hivemq-allow-all-extension](#disabling-the-hivemq-allow-all-extension)\n  * [Overriding the Cluster Bind Address](#overriding-the-cluster-bind-address)\n  * [Setting the Cluster Transport Type](#setting-the-cluster-transport-type)\n   \n# What is HiveMQ?\n\nHiveMQ 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. \nHiveMQ is built to address some of the key technical challenges organizations face when building new IoT applications, including:\n\n* Building reliable and scalable business critical IoT applications\n* Fast data delivery to meet the expectations of end users for responsive IoT products\n* Lower cost of operation through efficient use of hardware, network and cloud resources\n* Integrating IoT data into existing enterprise systems\n\nWhile 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.\n\nSee [Features](https://www.hivemq.com/features/) for more information.\n   \n# HiveMQ Docker Images\n\nThis repository provides the `Dockerfile` and context for the images hosted in the [HiveMQ Docker Hub repository](https://hub.docker.com/r/hivemq/hivemq4/).\n\n## HiveMQ Base Image\n\nThe [HiveMQ base image](hivemq4/base-image) installs and optimizes the HiveMQ installation for execution as a container.\n\nIt is meant to be used to build custom images or to run a dockerized HiveMQ locally for testing purposes.\n\n### How to Build\n\nThe image can then be built by running the command `HIVEMQ_VERSION=4.7.3 ./build.sh` in the `hivemq4/base-image` folder. An alternative image name can be specified with the environment variable `TARGETIMAGE`, example: `TARGETIMAGE=myregistry/custom-hivemq:1.2.3 HIVEMQ_VERSION=4.7.3 ./build.sh`\n\n## HiveMQ DNS Discovery Image\n\nThe [HiveMQ DNS discovery image](hivemq4/dns-image) is based on the HiveMQ base image and adds the [HiveMQ DNS Discovery Extension](https://www.hivemq.com/extension/dns-discovery-extension/).\n\nWe recommend using the HiveMQ DNS discovery image to run HiveMQ in a [cluster](#clustering).\n\n### How to Build\n\nTo build the DNS discover image, you must first obtain the [HiveMQ DNS Discovery Extension](https://www.hivemq.com/extension/dns-discovery-extension/), unzip the file and copy the folder to the `hivemq4/dns-image` folder.\n\nThe image can then be built by running `docker build -t hivemq-dns .` in the `hivemq4/dns-image` folder.\n\n## Tags\n\nThe [HiveMQ Docker Hub repository](https://hub.docker.com/r/hivemq/hivemq4/) provides different versions of the HiveMQ images using tags:\n\n| Tag | Meaning |\n| :--- | :---  |\n| latest | This tag will always point to the latest version of the [HiveMQ base image](#hivemq-base-image) |\n| dns-latest | This tag will always point to the latest version of the [HiveMQ DNS discovery image](#hivemq-dns-discovery-image) | \n| `\u003cversion\u003e` | [Base image](#hivemq-base-image) providing the given version of the broker (e.g. `4.0.0`) |\n| dns-`\u003cversion\u003e` | [DNS discovery image](#hivemq-dns-discovery-image) based on the given version base image |\n\n# Basic Single Instance\n\nTo start a single HiveMQ instance and allow access to the MQTT port as well as the Control Center, \n[get Docker](https://www.docker.com/get-started) and run the following command:\n\n`docker run --ulimit nofile=500000:500000 -p 8080:8080 -p 8000:8000 -p 1883:1883 hivemq/hivemq4`\n\nYou can connect to the broker via MQTT (1883) or Websockets (8000) or the Control Center (8080) via the respective ports.\n\n# Clustering\n\nFor running HiveMQ in a cluster, we recommend using the DNS discovery image.\nThis image has the [HiveMQ DNS Discovery Extension](https://www.hivemq.com/extension/dns-discovery-extension/) built in.\nIt can be used with any container orchestration engine that supports service discovery using a round-robin A record.\n\nA custom solution supplying the A record could be used as well.\n\n\n## Environment Variables\n\nThe following environment variables can be used to customize the discovery and broker configuration respectively.\n\n| Environment Variable | Default value | Meaning |\n| :-------- | :----- | :-------------- |\n| HIVEMQ_DNS_DISCOVERY_ADDRESS | - | Address to get the A record that will be used for cluster discovery |\n| HIVEMQ_DNS_DISCOVERY_INTERVAL | 31 | Interval in seconds after which to search for new nodes |\n| HIVEMQ_DNS_DISCOVERY_TIMEOUT | 30 | How long to wait for DNS resolution to complete |\n| HIVEMQ_CLUSTER_PORT | 8000 | Set the port to be used for the cluster transport |\n| HIVEMQ_BIND_ADDRESS | - | Set the *cluster transport* bind address, only necessary if the default policy (resolve hostname) fails |\n| HIVEMQ_CLUSTER_TRANSPORT_TYPE | UDP | Set the *cluster transport* type |\n| HIVEMQ_LICENSE | - | base64 encoded license file to use for the broker |\n| HIVEMQ_CONTROL_CENTER_USER | admin | Set the username for the HiveMQ Control Center login |\n| HIVEMQ_CONTROL_CENTER_PASSWORD | SHA256 of `hivemq` (default) | Set the password hash for HiveMQ Control Center authentication |\n| HIVEMQ_ALLOW_ALL_CLIENTS | true | Whether the default packaged allow-all extension (starting from `4.3.0`) should be enabled or not. If this is set to false, the extension will be deleted prior to starting the broker. This flag is inactive for all versions prior to `4.3.0`. |\n| HIVEMQ_REST_API_ENABLED | false | Whether the REST API (supported starting at `4.4.0`) should be enabled or not. If this is set to true, the REST API will bind to `0.0.0.0` on port `8888` at startup. This flag is unused for versions prior to `4.4.0`. |\n| HIVEMQ_VERBOSE_ENTRYPOINT | false | Whether the entrypoint scripts should print additional debug info. |\n\nFollowing are two examples, describing how to use this image on Docker Swarm and Kubernetes respectively.\n\nOther environments are compatible as well (provided they support DNS discovery in some way).\n\n## Entrypoint Scripts\n\nThere is a `/docker-entrypoint.d` directory which you can `COPY` custom entrypoint scripts to which will be executed before running HiveMQ.\nThe scripts must follow the `XX_name.sh` naming scheme, where `XX` is an integer number that will determine the ordering in which the entrypoint scripts are executed.\n\nDepending on the executable bit within the image, they will be either executed normally, or if the executable bit is not set, they will be sourced and run in the parent shell.\nSourcing allows you to set custom environment variables from an entrypoint script before startup.\n\n## Local Cluster with Docker Swarm\n\nTo start a HiveMQ cluster locally, you can use Docker Swarm.\n\n**Note:** Using Docker Swarm in production is not recommended.\n\n* Start a single node Swarm cluster by running:\n\n```\ndocker swarm init\n```\n* Create an overlay network for the cluster nodes to communicate on: \n\n```\ndocker network create -d overlay --attachable myNetwork\n```\n* Create the HiveMQ service on the network\n\n```\ndocker service create \\\n  --replicas 3 --network myNetwork \\\n  --env HIVEMQ_DNS_DISCOVERY_ADDRESS=tasks.hivemq \\\n  --publish target=1883,published=1883 \\\n  --publish target=8080,published=8080 \\\n  -p 8000:8000/udp \\\n  --name hivemq \\\n    hivemq/hivemq4:dns-latest\n```\n\nThis will provide a 3 node cluster with the MQTT (1883) and HiveMQ Control Center (8080) ports forwarded to the host network.\n\nThis means you can connect MQTT clients on port 1883. The connection will be forwarded to any of the cluster nodes.\n\nThe HiveMQ HiveMQ Control Center can be used in a single node cluster.\nA sticky session for the HTTP requests in clusters with multiple nodes cannot be upheld with this configuration, as the internal load balancer forwards requests in an alternating fashion.\nTo use sticky sessions the Docker Swarm Enterprise version is required.\n\n### Managing the Cluster\n\nTo scale the cluster up to 5 nodes, run\n\n```\ndocker service scale hivemq=5\n```\n\nTo remove the cluster, run\n\n```\ndocker service rm hivemq\n```\n\nTo read the logs for all HiveMQ nodes in real time, use\n\n```\ndocker service logs hivemq -f\n```\n\nTo get the log for a single node, get the list of service containers using \n\n```\ndocker service ps hivemq\n```\n\nAnd print the log using\n\n```\ndocker service logs \u003cid\u003e\n```\n\nwhere `\u003cid\u003e` is the container ID listed in the `service ps` command.\n\n## Production Use with Kubernetes\n\nNOTE: Please consider using the [Kubernetes Operator](https://docs.hivemq.com/hivemq-platform-operator/introduction.html) instead, as it makes production deployment of HiveMQ much easier.\n\nFor production we recommend using the DNS discovery image in combination with Kubernetes.\n\nOn Kubernetes, an appropriate deployment configuration is necessary to utilize DNS discovery.\nA [headless service](https://kubernetes.io/docs/concepts/services-networking/service/#headless-services) will provide a DNS record for the broker that can be used for discovery.\n\nFollowing is an example configuration for a HiveMQ cluster with 3 nodes using DNS discovery in a replication controller setup.\n\nPlease note that you may have to replace `HIVEMQ_DNS_DISCOVERY_ADDRESS` according to your Kubernetes namespace and configured domain.\n\n```\napiVersion: v1\nkind: ReplicationController\nmetadata:\n  name: hivemq-replica\nspec:\n  replicas: 3\n  selector:\n    app: hivemq-cluster1\n  template:\n    metadata:\n      name: hivemq-cluster1\n      labels:\n        app: hivemq-cluster1\n    spec:\n      containers:\n      - name: hivemq-pods\n        image: hivemq/hivemq4:dns-latest\n        ports:\n        - containerPort: 8080\n          protocol: TCP\n          name: hivemq-control-center\n        - containerPort: 1883\n          protocol: TCP\n          name: mqtt\n        env:\n        - name: HIVEMQ_DNS_DISCOVERY_ADDRESS\n          value: \"hivemq-discovery.default.svc.cluster.local.\"\n        - name: HIVEMQ_DNS_DISCOVERY_TIMEOUT\n          value: \"20\"\n        - name: HIVEMQ_DNS_DISCOVERY_INTERVAL\n          value: \"21\"\n        - name: HIVEMQ_CLUSTER_TRANSPORT_TYPE\n          value: \"TCP\"\n        readinessProbe:\n          tcpSocket:\n            port: 1883\n          initialDelaySeconds: 30\n          periodSeconds: 60\n          failureThreshold: 60\n        livenessProbe:\n          tcpSocket:\n            port: 1883\n          initialDelaySeconds: 30\n          periodSeconds: 60\n          failureThreshold: 60\n---\nkind: Service\napiVersion: v1\nmetadata:\n  name: hivemq-discovery\n  annotations:\n    service.alpha.kubernetes.io/tolerate-unready-endpoints: \"true\"\nspec:\n  selector:\n    app: hivemq-cluster1\n  ports:\n    - protocol: TCP\n      port: 1883\n      targetPort: 1883\n  clusterIP: None\n```\n\n### Accessing the HiveMQ Control Center\n\nTo access the HiveMQ HiveMQ Control Center for a cluster running on Kubernetes, follow these steps:\n\n* Create a service exposing the HiveMQ Control Center of the HiveMQ service. Use the following YAML definition (as `web.yaml`):\n\n```\nkind: Service\napiVersion: v1\nmetadata:\n  name: hivemq-control-center\nspec:\n  selector:\n    app: hivemq-cluster1\n  ports:\n    - protocol: TCP\n      port: 8080\n      targetPort: 8080\n  sessionAffinity: ClientIP\n  type: LoadBalancer\n```\n\n* Create the service using `kubectl create -f web.yaml`\n\n**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.\n\n### Accessing the MQTT Port Using External Clients\n\nTo allow access for the MQTT port of a cluster running on Kubernetes, follow these steps:\n\n* Create a service exposing the MQTT port using a load balancer. You can use the following YAML definition (as `mqtt.yaml`):\n\n```\nkind: Service\napiVersion: v1\nmetadata:\n  name: hivemq-mqtt\n  annotations:\n    service.spec.externalTrafficPolicy: Local\nspec:\n  selector:\n    app: hivemq-cluster1\n  ports:\n    - protocol: TCP\n      port: 1883\n      targetPort: 1883\n  type: LoadBalancer\n```\n\n* Create the service using `kubectl create -f mqtt.yaml`\n\n**Note:** The `externalTrafficPolicy` annotation is necessary to allow the Kubernetes service to maintain a larger amount of concurrent connections.  \nSee [Source IP for Services](https://kubernetes.io/docs/tutorials/services/source-ip/#source-ip-for-services-with-type-nodeport) for more information.\n\n# Configuration\n\n## Setting the HiveMQ Control Center Username and Password\n\nThe 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.\n\nAdditionally, you can also configure the username, using the environment variable `HIVEMQ_CONTROL_CENTER_USER`.\n\nSee [Generate a SHA256 Password](https://docs.hivemq.com/hivemq/latest/control-center/configuration.html#generate-password) to read more about how to generate the password hash.\n\n## Adding a License\n\nTo use a license with a HiveMQ docker container, you must first encode it as a string.\n\nTo do so, run `cat license.lic | base64` (replace `license.lic` with the path to your license file).\n\nSet the resulting string as the value for the `HIVEMQ_LICENSE` environment variable of the container.\n\n## Disabling the hivemq-allow-all-extension\n\nBy default the HiveMQ docker images use the packaged `hivemq-allow-all-extension`.\n\nThis can be circumvented by setting the `HIVEMQ_ALLOW_ALL_CLIENTS` environment variable to `false`.\n\nThis will cause the entrypoint script to delete the extension on startup.\n\n## Overriding the Cluster Bind Address\n\nBy 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.\n\nThis 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.\n\n## Setting the Cluster Transport Type\n\nBy default the HiveMQ DNS discovery image uses UDP as transport protocol for the cluster transport.\n\nIf you would like to use TCP as transport type instead, you can set the `HIVEMQ_CLUSTER_TRANSPORT_TYPE` environment variable to `TCP`.\n\n**Note:** We generally recommend using TCP for the cluster transport, as it makes HiveMQ less susceptible to network splits under high network load.\n\n## Building a custom Docker image\n\nSee [our documentation](https://docs.hivemq.com/hivemq/latest/user-guide/docker.html#custom) for more information on how to build custom HiveMQ images.\n\n# Contributing\nIf you want to contribute to HiveMQ 4 Docker Images, see the [contribution guidelines](CONTRIBUTING.md).\n\n# License\n\nHiveMQ 4 Docker Images is licensed under the `APACHE LICENSE, VERSION 2.0`. A copy of the license can be found [here](LICENSE).\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhivemq%2Fhivemq4-docker-images","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhivemq%2Fhivemq4-docker-images","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhivemq%2Fhivemq4-docker-images/lists"}