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.

mkdir hivemq-docker
vim hivemq-docker/Dockerfile

The Dockerfile:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

#
# HiveMQ Dockerfile
#

# Pull base image. The official docker openjdk-8 image is used here.
FROM java:8-jdk

#Install wget and unzip, then download and install HiveMQ.
RUN \
    apt-get install -y wget unzip &&\
    wget --content-disposition <YOUR-HIVEMQ-DOWNLOAD-LINK> &&\
    unzip hivemq-*.zip -d /opt/ &&\
    mv /opt/hivemq-* /opt/hivemq
  
# Define working directory.
WORKDIR /opt/hivemq

# Define HIVEMQ_HOME variable
ENV HIVEMQ_HOME /opt/hivemq

# Expose MQTT port
EXPOSE 1883

# Define default command. Here we use HiveMQ's run script.
CMD ["/opt/hivemq/bin/run.sh"]

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

docker images

You should see something like the following

1
2
3

REPOSITORY          TAG                 IMAGE ID            CREATED             VIRTUAL SIZE
hivemq              3.1.2               9bfaa5ae8578        15 seconds ago      677.7 MB
java                8-jdk               c518da75d9f0        10 days ago         642.9 MB

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.

1

docker run -d -p 11883:1883 --name=hivemq-container hivemq:3.1.2

Now we can check if the container is running with

docker ps -a

which returns something like

1
2

CONTAINER ID        IMAGE              COMMAND                CREATED             STATUS                 PORTS                     NAMES
109caf77c159        hivemq:3.1.2       "/opt/hivemq/bin/run   6 minutes ago       Up 2 minutes           0.0.0.0:11883->1883/tcp   hivemq-container

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

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.

1

docker run -d -p 11883:1883 --name=hivemq-container -v /opt/hivemq/data hivemq:3.1.2

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.

1
2
3

cd ~
mkdir hivemq-data
docker run -d -p 11883:1883 --name=hivemq-container -v ~/hivemq-data:/opt/hivemq/data hivemq:3.1.2

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 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:

vim hivemq-container/config.xml
vim hivemq-container/Dockerfile

config.xml (with additional websocket listener)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

<?xml version="1.0"?>
<hivemq xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="hivemq-config.xsd">
<listeners>
    <tcp-listener>
        <port>1883</port>
        <bind-address>0.0.0.0</bind-address>
    </tcp-listener>
    <websocket-listener>
      <port>8000</port>
      <bind-address>0.0.0.0</bind-address>
      <path>/mqtt</path>
      <subprotocols>
          <subprotocol>mqttv3.1</subprotocol>
          <subprotocol>mqtt</subprotocol>
      </subprotocols>
  </websocket-listener>
</listeners>
</hivemq>

Dockerfile (with added COPY and EXPOSE command)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

#
# HiveMQ Dockerfile
#

# Pull base image. The official docker openjdk-8 image is used here.
FROM java:8-jdk

#Install wget and unzip, then download and install HiveMQ.
RUN \
    apt-get install -y wget unzip &&\
    wget --content-disposition <YOUR-HIVEMQ-DOWNLOAD-LINK> &&\
    unzip hivemq-*.zip -d /opt/ &&\
    rm -f hivemq-*.zip &&\
    mv /opt/hivemq-* /opt/hivemq
  
# Define working directory.
WORKDIR /opt/hivemq

# Define HIVEMQ_HOME variable
ENV HIVEMQ_HOME /opt/hivemq

# Install the HiveMQ config file
COPY config.xml /opt/hivemq/conf/config.xml

# Expose MQTT port
EXPOSE 1883
# Expose MQTT over Websocket port
EXPOSE 8000

# Define default command. Here we use HiveMQ's run script.
CMD ["/opt/hivemq/bin/run.sh"]

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

1
2

docker build -t hivemq:3.1.2 hivemq-docker/
docker run -d -p 11883:1883 -p 18000:8000 --name=hivemq-container -v ~/hivemq-data:/opt/hivemq/data hivemq:3.1.2

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.

Conclusion

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.

About HiveMQ Team

We love writing about MQTT, IoT protocols and architecture in general. Our experts are here to help, so reach out to us if we can help!

Contact HiveMQ