Deploying HiveMQ With Docker

Containerized deployments are getting more popular every day for scalable software infrastructures. It’s easy to build maintainable and developer-friendly environments with container solutions like Docker. This post explores how HiveMQ can be used in conjunction with Docker for creating maintainable, scalable and easy-to-use MQTT server deployments.

What is Docker?

Docker is a software project, which aims to automate the deployment of applications by utilizing software containers. It allows you to operate portable infrastructure environments which your application runs in. And, since HiveMQ might be a part of your application, this blog post will give you a quick introduction on how to run HiveMQ inside a Docker container.

Should I use Docker?

Docker, together with HiveMQ, might be a very viable solution, depending on your use-case. Although Docker adds complexity to your infrastructure setup, it may also come with some advantages, especially if you are looking for a large-scale deployment, which has to be very flexible and elastic.

The basic advantages of Docker are:

• Reduced risk and effort for the operations team because a deployment is always automated which means less manual actions are needed.

• Reduced overhead (in comparison to traditional virtualization) since multiple containers share resources and a guest operating system.

• Solid documentation because Docker provides Infrastructure as Code by being configured in a descriptive manner. That means the infrastructure is always documented and changes can be tracked via version control systems like git or SVN.

• Easy repeated deployments which simplifies a deployment of multiple HiveMQ nodes for a cluster.

• Increased Testability because the development team can use the same environment that will run in production.

The basics

Getting started

If you have not used docker before, it’s recommended to take a look at the excellent tutorials from Docker for Windows, Mac OS X or Linux. These tutorials will guide you through the installation and setup process of Docker and give you a good starting point on how to operate the available tools provided by Docker.

Creating an image

To run HiveMQ on Docker a custom Dockerfile is the way to go. This Dockerfile describes how the base image for all HiveMQ containers is built.

We will use the java image available on dockerhub as a basis for our HiveMQ image. The base image already handles the installation of openjdk-8, so we can focus solely on installing HiveMQ.

Let’s start with creating a folder and a Dockerfile in it. Replace YOUR-HIVEMQ-DOWNLOAD-LINK with your personal download link which you get from the HiveMQ Download page.

The Dockerfile:

After creating the files we can tell Docker to build the image. You can specify a name and a tag for the image with the -t parameter, which can be used later on to identify the image. Here hivemq is used as the name and the current HiveMQ version 3.1.2 is used as tag. You can change this to fit your needs.

docker build -t hivemq:3.1.2 hivemq-docker/

Then check if the image is available by executing

You should see something like the following

Creating a container

Now that the image is created we can start a new container as a daemon (-d) with the exposed MQTT port mapped to the port 11883 (-p 11883:1883) on the docker host and the name hivemq-container.

Now we can check if the container is running with

which returns something like

Congratulations, you now have a running Docker container with a running HiveMQ inside.

You can now connect to HiveMQ with your preferred MQTT tool with the following connection settings

• Host: IP/hostname of your docker host (e.g. localhost)

• Port: 11883

Stopping the container

You can stop the container with

and delete the container with

Volumes

HiveMQ stores persistent data - like MQTT persistent session information - on disk to prevent the data from getting lost in case of a restart. To retain HiveMQ’s persistent data when recreating or updating a docker container we can utilize Docker’s virtual volumes.

A volume is basically a folder on the Docker host that gets mounted on the docker container. That means the data which is written inside the docker container will appear on the docker host where it is still stored even if the container is deleted.

Fortunately HiveMQ stores all its persistent data in the $HIVEMQ_HOME/data folder, so we can simply add this folder as a volume. We only need to add the -v parameter to the run command and point it to HiveMQ’s data folder inside the container.

NOTE: The same mechanism can be used for other folders like HiveMQ’s log folder. Docker supports multiple occurrences of the -v parameter.

Docker will create a folder on the host for you automatically, but you can also specify a folder on the host where you want the persistent data to be stored.

WARNING: Do not use the same data folder on the docker host for multiple HiveMQ containers. Each HiveMQ container needs its own data folder to work as expected.

HiveMQ MQTT Broker Configuration

Until now the HiveMQ container runs with HiveMQ’s default configuration. This might not be enough for your use-case if you want to use Websockets or TLS for example.

To allow easy configuration of HiveMQ you can add a config.xml for HiveMQ to the hivemq-container folder and add a line to your Dockerfile which tells Docker to install this configuration file.

Example with enabling websockets:

config.xml (with additional websocket listener)

Dockerfile (with added COPY and EXPOSE command)

you can now build and run the container with (note the second -p parameter for the websocket port)

You can now connect to HiveMQ with a websocket capable MQTT Client, like the HiveMQ Websocket MQTT Client with the following credentials:

• Host: IP/hostname of your docker host (e.g. localhost)

• Port: 18000

NOTE: The same mechanism can be used to install other configuration files, for example plugin configuration files.

HiveMQ Cluster on Docker

This blog post should have given you a basic idea on how to run HiveMQ on Docker. But Docker’s real strengths lay in multi-container deployments and together with HiveMQ’s dynamic clustering feature you can really benefit from this. This is why the next blog post will focus on a HiveMQ cluster setup on Docker and shed some light on the configuration needed to get a cluster up and running.

Conclusion

Docker and HiveMQ MQTT Broker work together perfectly with minimal configuration effort. This blog post explored how easy a full-fledged containerized HiveMQ deployment can be created for development, testing, integration and production purposes.