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.
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.
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
Now we can check if the container is running with
docker ps -a
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
docker stop hivemq-container
and delete the container with
docker rm hivemq-container
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
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.
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
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 blogpost 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 blogpost will focus on a HiveMQ cluster setup on Docker and shed some light on the configuration needed to get a cluster up and running.
Docker and HiveMQ 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.
Stay tuned for the next blog post about deploying a HiveMQ cluster with Docker. In the meantime, let us know in the comments what your preferred HiveMQ deployment option is.