HiveMQ: New on Docker Hub

by Florian Raschbichler

Nov 21, 2018 10 min read

The popularity of Docker for deploying all kinds of applications and services in a containerized environment has been increasing exponentially. That’s not surprising since orchestration platforms such as Kubernetes, Docker Swarm, and Mesos keep improving functionality for running containers. The ability to integrate Docker with different cloud infrastructures (think load balancers, block storage) and enterprise grade platforms for bare metal installations makes building complex services from basic container images a breeze.

Here at HiveMQ we’re happy to announce the introduction of a continuously updated HiveMQ Docker repository on Docker Hub that can help you streamline your development and deployment efforts.

Overview

Our Docker repository will provide a single location for the container images of select past, current, and future versions of HiveMQ. You can use these images to run HiveMQ instances on the Docker daemon instance of your choice. As well as a pre built DNS discovers image that already includes the DNS discovery plugin, which is tailor made for containerized, orchestrated deployments leveraging technologies like Kubernetes.

The images adhere to all Dockerfile best practices as defined by Docker: Best practices for writing Dockerfiles and the documentation in Docker library: official images.

Base Image

Running a basic installation of the most recent HiveMQ version is now as easy as installing Docker and entering a single command:

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

The first time you run the command, it pulls the most recent version of HiveMQ from Docker Hub and runs it in a container. The file system and processes of the HiveMQ container are isolated from the host. You are now able to connect MQTT clients on port 1883 on your local machine and access the Web UI on

http://localhost:8080

The Base Image is meant to provide a quick possibility to start a HiveMQ single node for testing purposes. You can also use this base image to build your own custom image and include any files that you need, such as:

Customized configuration files
Custom plugins and the corresponding configurations
License files
Custom entry point scripts (for configuring at start up)

DNS Discovery Image

If you want to run a containerized HiveMQ cluster, we strongly recommend using this image. It already contains the HiveMQ DNS cluster discovery plugin and is designed to be used with orchestration software that provides a Round-robin A-record DNS service.

Run a local cluster with Docker Swarm

Note that we do not recommend using Docker Swarm in production instead we recommend the use of Kubernetes.

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, using the lates HiveMQ DNS discovery docker image:

Example HiveMQ Service for Docker Swarm

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 the MQTT(1883) and Web UI(8080) ports forwarded to the host network.
Meaning you can connect MQTT clients on port 1883. The connection will be forwarded to any of the cluster nodes.
The HiveMQ Web UI can be used in a single node cluster. A 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. To enable the use of sticky sessions, the Docker Swarm Enterprise version is required.

Managing the cluster

To scale the cluster up to 5 nodes, run

docker service scale hivemq=5

To remove the cluster, run

docker service rm hivemq

To read the logs for all HiveMQ nodes in real time, use

docker service logs hivemq -f

To get the log for a single node, get the list of service containers using

docker service ps hivemq

And print the log using

docker service logs <id>

where is the container ID listed in the service ps command.

Adding a HiveMQ license

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

cat path/to/your/license.lic | base64

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

HiveMQ and Kubernetes

We recommend running HiveMQ with Kubernetes, when running a containerized HiveMQ depoyment in production. Please refer to this detailed blog post on running a HiveMQ cluster in Kubernetes for more information.

Building a custom image

As mentioned in the overview, you can build your own image from the provided base image and utilize any of the provided HiveMQ versions. Here is an example of a Dockerfile that does all of the following:

ARG TAG=latest
# (1)
FROM hivemq/hivemq3:${TAG} 
# (2)
ENV MY_CUSTOM_PLUGIN_ENV myvalue 
# (3)
ENV HIVEMQ_CLUSTER_PORT 8000

# (4)
COPY --chown=hivemq:hivemq your-license.lic /opt/hivemq/license/your-license.lic 
COPY --chown=hivemq:hivemq myconfig.xml /opt/hivemq/conf/config.xml
COPY --chown=hivemq:hivemq myplugin.jar /opt/hivemq/plugins/myplugin.jar
COPY --chown=hivemq:hivemq myentrypoint.sh /opt/myentrypoint.sh
# (5)
RUN chmod +x /opt/myentrypoint.sh 
# (6)
ENTRYPOINT ["/opt/myentrypoint.sh"]

Uses the hivemq/hivemq3:latest image as a base, with a build argument that (optionally) specifies which base tag to use.
Defines an environment variable for the plugin.
Defines an environment variable that is substituted in the HiveMQ configuration file on start up. For details, see Using environment variables for configuration.
Copies required files such as a valid HiveMQ license file, a customized configuration, a custom plugin file and custom entry point to the corresponding folders and applies proper ownership inside the container.
Sets the custom entry point as executable.
Defines the entry point for the image. This definition is optional, but it allows you to run additional commands or programs (for configuration purposes) before you start the actual HiveMQ instance.

Here is one way that you can build the Dockerfile:

docker build --build-arg TAG=3.4.2 -t hivemq-myplugin .

The result is an image built on the HiveMQ base image version 3.4.2 and the current path as the build context. The finished image is tagged locally as

hivemq-myplugin:latest

Tagging and build scheme

The following tags are designed to simplify the use of the HiveMQ base image in scripts and Dockerfiles:

latest: This tag will always point to the latest version of the HiveMQ base image.
dns-latest: This tag will always point to the latest version of the HiveMQ DNS discovery image.
{version}: Base image providing the given version of the broker (e.g. 3.4.2)
dns-{version}: DNS discovery image providing the given version of the broker (e.g. 3.4.2)

The builds are based on the Dockerfiles defined in hivemq-docker-images.

For more information on tags and other metadata, refer to the Docker Hub page.

Florian Raschbichler

Florian serves as the head of the HiveMQ support team with years of first hand experience overcoming challenges in achieving reliable, scalable, and secure IoT messaging for enterprise customers.