Get an IBM MQ queue for development in a container

To see how IBM MQ works, you will be guided through creating and configuring a queue manager (server). Then, you will connect an application (client) to it.

After completing the tutorial, you will be able to send messages to and retrieve messages from a queue.

You can download, install, and run IBM MQ queue manager (server) in a variety of ways:

• In a container (this tutorial) or Red Hat OpenShift Container Platform.
• In the IBM Cloud, AWS (or AWS using Ansible or AWS using Terraform), Microsoft Azure, or Google Cloud.
• On various operating systems: Linux/Ubuntu or windows. For macOS, use MQ on Containers (this tutorial).

Learning objectives

After completing this tutorial, you will understand these concepts:

• IBM MQ queue managers
• IBM MQ queues
• Point-to-point messaging

Prerequisites

• Either Docker Desktop or Podman (see Step 1)
• The IBM MQ Docker image

Estimated time

This tutorial should take about 30 minutes.

Steps

If you'd rather watch a video to learn how to install MQ in a container, you can watch this one.

Step 1. Install Docker or Podman

Important: In August 2021, Docker announced changes to their product subscription model. While Docker Desktop for macOS and windows remains free for certain users under the terms of Docker’s Personal tier, those users working in larger organizations and groups may be required to subscribe to one of Docker’s paid subscription tiers. These changes will take effect starting on January 31, 2022.

Download and install Docker from Docker Hub. Then, follow the instructions in the installation documentation to install Docker.

Docker images are generated in an OCI standard format and are compatible with Podman, an open source, Linux-native tool. (Read more about transitioning to Podman in this Red Hat Developer blog.) If you do not want to (or cannot) subscribe to one of Docker’s paid subscription tiers, you can use Podman as an alternative to complete this tutorial.

To install Podman, follow the instructions in the Podman installation documentation.
(If you are facing issues with installing Podman on windows using the instructions in the Podman documentation, perhaps these installation instructions we've written will be a suitable alternative.) If you run into issues using Podman to create MQ containers, make sure that the client and server version for Podman is the same (which you can learn more in this community blog).

The instructions in this tutorial have commands that use Podman. If you are using Docker instead, run the following command to set up an alias, which will allow you to still use the podman commands in the instructions.

For Mac and Linux:

alias podman=’docker’

For windows (PowerShell):

Set-Alias podman docker

If you don’t want to set up an alias for the podman command, you can simply replace podman with “docker” in this tutorial.

Step 2. Get the MQ in Container image

IMPORTANT: Apple Silicon Mac users: The current container hosted on public container registries is X86_64 based, and incompatible with Apple Silicon (ARM 64) Mac computers. The -platform emulation option will not work on Apple Silicon Mac computers. If you are using one of these Mac computers, you will need to build and run an IBM MQ container image natively following these instructions and then skip this step.

Containers are run from images and images are built from a specification listed in a Dockerfile. We will use a pre-built IBM MQ server image so that we can just run our container without having to build an image. We will end up with a working MQ installation and a queue manager that is preconfigured with objects ready for developers to work with.

1. Pull the image from the IBM Container Registry that contains the latest version of the MQ server.

   podman pull icr.io/ibm-messaging/mq:latest

   Copy code

2. When it's done, check which images you have:

   podman images

   Copy code

   You should see output like this:

Step 3. Run the container from the image

Now that the MQ server image is in your local image repository, you can run the container to stand up MQ in RHEL in a container.

When you stand up a container, an in-memory file system is used that is deleted when the container is deleted. Queue manager and queue data is saved in this file system. To avoid losing the queue manager and queue data, we can use Volumes.

Volumes are attached to containers when they are run and persist after the container is deleted. When you run a new container you can attach an existing volume and later reuse your queue manager and queue data.

1. Use Docker or Podman to create a volume.

   podman volume create qm1data

   Copy code

2. Run the MQ server container. Edit the command to set your own password for connecting applications. You will need this password later, for both the client demo application and when you run your own client applications. In this example, we're setting the password to "passw0rd" but you can also choose your own.

   Important: If you are working on an Apple Silicon (ARM 64) Mac computer, you might have a different image. To check your image details run the command podman images. Then ensure that you change the following run command appropriately: --name imageName:tag.

   podman run --env LICENSE=accept --env MQ_QMGR_NAME=QM1 --volume qm1data:/mnt/mqm --publish 1414:1414 --publish 9443:9443 --detach --env MQ_APP_USER=app --env MQ_APP_PASSWORD=passw0rd --env MQ_ADMIN_USER=admin --env MQ_ADMIN_PASSWORD=passw0rd --name QM1 icr.io/ibm-messaging/mq:latest

   Copy code

If you prefer to set the app and admin passwords using secrets, then see the IBM MQ container documentation, "Using secrets to set passwords for app & admin users," for how to create the secrets and pass them to the container.

Your queue manager has been set up with some simple default configuration to help you connect your first client application.

We've added parameters to the docker run command, for example to accept the license for IBM MQ Advanced for developers and name the queue manager "QM1" where our queue will live.

Because MQ is running inside a container, it would be isolated from the rest of the world, so we've opened a couple of ports that MQ uses.

The queue manager's listener listens on port 1414 for incoming connections and port 9443 is used by MQ console.

The MQ demo client application will use the listener port and MQ Console dashboard can be seen in your browser on port 9443.

Give the container a moment to start, and then check that it's running.

podman ps

You should see output like this:

Congratulations! You've just created your first simple queue manager. It's called QM1, and it's running inside the container.

To access this queue manager, you'll be connecting over TCP/IP, which is why you needed to expose the port 1414.

You can use the container name to get command line access inside the container or make a note of your own container ID and use that instead. In the run step, we named our container 'QM1'. For example:

podman exec -ti QM1 bash

You should see output like this:

You can display the MQ installation and data paths by running the dspmqver command (display MQ version) in your command line interface.

dspmqver

You should see output like this:

You can display your running queue managers using the dspmq command.

dspmq

You should see output like this:

To come out of the Docker container and return to your command line, type exit and press Enter.

What you've done so far

You downloaded the pre-built Docker image and ran the container to get MQ running on RHEL. The IBM MQ objects and permissions that the client applications need to connect to a queue manager and to be able to put and get messages to and from the queue are created automatically. Docker and MQ are using your host computer resources and connectivity.

Inside the container, the MQ installation on RHEL has the following objects:

• Queue manager QM1
• Queue DEV.QUEUE.1
• Channel: DEV.APP.SVRCONN
• Listener: SYSTEM.LISTENER.TCP.1 on port 1414

The queue that you will be using, DEV.QUEUE.1, "lives" on the queue manager QM1. The queue manager also has a listener that listens for incoming connections, for example, on port 1414. Client applications can connect to the queue manager and can open, put, and get messages, and close the queue.

Applications use an MQ channel to connect to the queue manager. Access to these three objects is restricted in different ways. For example, user "app", who is a member of the group "mqclient" is permitted to use the channel DEV.APP.SVRCONN to connect to the queue manager QM1 and is authorized to put and get messages to and from the queue DEV.QUEUE.1.

All the MQ objects and permissions that the client application needs are created and configured when you run the MQ server container.

Summary

In this tutorial, you stood up an MQ queue manager in a container, which came with a preset developer configuration to allow incoming client connections.

When you start developing your own client applications to connect to the queue manager, you'll follow these steps:

1. Configure the connection to the queue manager.
2. Open a queue.
3. Put a message on the queue.
4. Get the message from the queue.
5. Close the connection to the queue manager.

This process demonstrates point-to-point style of messaging.

In IBM MQ, the queue manager is effectively the server part of the system, and applications that connect to it are clients.

Usually it is the administrators that look after the MQ server where all the MQ objects are defined and the routing of messages happens. Client applications are created by developers and IBM MQ provides client libraries that developers must include in their applications. These libraries, also called MQ clients, address and use the MQ objects that admins have set up on the MQ server side. In more complex scenarios, the MQ libraries do most of the heavy messaging work for you, so you just have to learn how to use them.

Configuration is needed on both the server and the client sides for the messaging to work.

When you first start developing MQ client applications, you need to have access to your own queue manager and a queue, for testing your client application against. The preconfigured MQ in Docker image and the container that you can easily run from it gives you access to a queue manager and many options for configuring MQ objects as you begin developing your own MQ applications.