Use the official AMQ Broker image for development

A local instance of an AMQ Broker is handy when developing an integration or application that needs to produce or consume messages. If not necessary.

There are of course several options. In the past, I tended to do a local installation of such a product. Nowadays, I find a Docker image more convenient. I prefer one from an official registry, where the image is actively maintained by a trusted organization. The maintainers do the installation for you. You can just grab an image from the official registries and, in the case of AMQ, provide a broker.xml. Adding to that, Docker-compose also allows you to create a context with multiple service images that run as a swarm. By doing so, the services can run together in a separated Docker network.

We used to have a Dockerfile to build an Artemis Broker image from scratch based on a basic openjdk8 image. In the Dockerfile the Artemis broker software is downloaded and installed. After that, the broker instance is created. And that on every docker-compose build. That is quite a bit of overkill.

The current latest official Red Hat AMQ image can be found here. Or search in the registry for “AMQ Broker”.

There are (at least) two ways to use this in a docker-compose setup.

Environment variable BROKER_XML

The image checks the BROKER_XML variable content for the broker.xml settings. So basically you’ll have to cat your broker.xml to that variable and then spin up your container.

I created a small docker-compose.yml file on github.com. In the broker subfolder, you’ll find an example broker.xml.

You start this example with:

Starting the broker container

With docker ps you can see the container running:

Running AMQ Broker container

And with docker exec -it $CONTAINER_ID /bin/bash you can start a shell into the container:

BROKER_XML content in the container shell

In the console you can check that the acceptors and addresses in the BROKER_XML are actually loaded:

Broker Acceptors and addresses

This is nice. But the need to first load the broker.xml into an environment variable can get in the way with scripting and other uses. I wanted a way that just gets the broker.xml from the filesystem.

Bind Volume

A how-to from Stuart Winchester gave a hint for me. He describes several options, and one of them is to mount a configmap-resource when using the broker in OpenShift. So apparently, the image is also able to get the broker.xml from the /opt/amq/conf/broker.xml path within the container.

This folder contains only one file in the container as running in the previous example:

Contents of the amq configuration folder

I created a copy of the previous example on github.com. This folder has a slightly different docker-compose.yml. It looks like:

Volumes element in docker-compose.yml

Instead of setting the BROKER_XML variable, the ./broker/broker.xml is bound to the /opt/amq/conf/broker.xml file in the container.

Now, you only have to do docker-compose up -d to get the container running:

Start container with bound broker.xml

And as described above, we can connect to the container shell and check the config folder:

Check containers amq configuration folder

Here you see that the broker.xml is bound into the container

And again you can check the console to see the acceptors and addresses from the broker.xml:

Conclusion

This is a very easy way to spin up a AMQ Artemis broker from a certified container. That can also be used within an OpenShift cluster. Which helps in development.

If you want to check out my previous article about using SoapUI against a AMQ Broker, then this setup might help as well.