Appendix A: How to run a free Docker IBM® MQ for Developers on Windows, Linux and AWS EC2

IBM have released a special IBM® MQ for Developers (and Testers) you can run for free. There are two main options how to run it.

• Install on your laptop/server/VM
• Use the docker image

We will focus on the docker version, because it is easier to set up in our opinion. Not everybody has access to a Linux box, so we will show you how to use the free tier AWS EC2 virtual machine for that.

Unfortunately it is not possible to run Docker Linux images on Windows systems. So you cannot run a Docker IBM MQ for Developers on your Windows laptop. To work around that we will use a free AWS Linux virtual machine. We will sign up for a free AWS EC2 account, run a Linux VM there, install docker and run IBM MQ. AWS free tier will allow you to use a Linux host for a year free of charge.

Follow these steps to install a Docker IBM® MQ for Developers on AWS free tier:

1. Create a free account on the AWS website. You will need a credit or debit card to register, but it will not be charged as long as you use the free tier only. Please note it might take up to 24 hours to activate your account.
2. Create a linux virtual machine instance on AWS EC2. Make sure you keep the PEM file you have downloaded, you will use it to connect to the virtual machine very soon using PuTTY.
3. Download PuTTY and PuTTYGen
4. Connect using PuTTY to your AWS EC2 Linux instance
5. You should now see a PuTTY connected to your instance

   

6. Run the following commands to update yum and install docker, and make sure you do not get any errors:

   sudo yum update -y
   sudo yum install docker -y

   

   sudo service docker start

   

   sudo docker run hello-world

   

7. Display, read and make sure you understand and are OK with the IBM® MQ license by running:

   sudo docker run --env LICENSE=view icr.io/ibm-messaging/mq:9.4.4.0-r4

   You will be accepting the license in the next step.

   

8. Run Docker MQ (please notice that by setting LICENSE=accept you are accepting the license you have seen in the previous step):

   sudo docker run --env LICENSE=accept --env MQ_QMGR_NAME=QM1 --volume /var/example:/mnt/mqm --publish 1414:1414 --publish 9443:9443 --detach icr.io/ibm-messaging/mq:9.4.4.0-r4

   

9. Allow for connections from your IP to the AWS EC2 instance on ports used by IBM® MQ (1414 and 9443) by adding new rules to the security group. Note that if your IP changes, you will loose the connectivity and have to do this step again.
10. You can test the connection by using a web browser to connect to the web console. Open this URL in your browser https://your-ec2-hostname:9443/admin/ and use username admin and password passw0rd.
11. Done! Your MQ instance is up and running. You can now try connecting to it with your application and Traffic Parrot by pointing them at your-ec2-hostname, port 1414, queue manager name QM1, username app and an empty password. There are a few default queues and topics defined there which you can use, if you need more you will have to add them. For more details see instruction at the official IBM® MQ docker image website.
12. Next step, follow the JMS IBM® MQ mocking and service virtualization tutorial to learn how to simulate systems communication using IBM® MQ queues and topics and test your software in isolation. It will help you find more bugs and reduce time it takes to test.

The Docker IBM® MQ for Developers image is straightforward to start, but a handful of issues come up often enough to call out. Each of the items below names a symptom you will see and the resolution that fixes it.

Connection refused on port 1414 or 9443

If your JMS client, Traffic Parrot, or the web console cannot reach the queue manager and you see Connection refused or timed out, the most common cause is the AWS EC2 security group blocking the port. Open the EC2 console, find the security group attached to your instance, and add inbound rules allowing TCP 1414 (queue manager client connections) and 9443 (web console) from your client IP. Remember that your public IP can change — if connectivity stops working after a few days, re-check the security group rule. A second possibility: the container did not start. Run sudo docker ps and confirm a container based on icr.io/ibm-messaging/mq is listed; if it is missing, run sudo docker ps -a to find the exited container and sudo docker logs <container-id> to read why it exited.

Container exits immediately

If sudo docker run returns straight to the shell and sudo docker ps shows no running container, the most likely cause is that you did not pass --env LICENSE=accept. IBM® MQ refuses to start without an explicit license acknowledgement and will log a message before exiting. Read sudo docker logs <container-id> to confirm; then re-run the command from the previous step, making sure the LICENSE=accept flag is present.

Old image name (ibmcom/mq) no longer pulls

Older tutorials reference ibmcom/mq on Docker Hub. That image has been deprecated; the current location is icr.io/ibm-messaging/mq on the IBM Container Registry, and the commands in this appendix already use it. If a copy-pasted command fails with manifest unknown or pull access denied, swap the image reference to the icr.io name and re-run.

Client cannot find the queue manager

If Traffic Parrot or your application connects but then reports MQRC_Q_MGR_NAME_ERROR or a similar 2058 error code, the queue manager name configured on the client does not match what the container is running. The example commands above set MQ_QMGR_NAME=QM1 — confirm both the container env var and the client configuration agree. The web console at https://your-ec2-hostname:9443/admin/ shows the queue manager name once you sign in.

Authentication failures (2035, MQRC_NOT_AUTHORIZED)

The developer image ships with two pre-configured identities: the web console uses admin / passw0rd (note the digit zero) and client connections use app with an empty password. If you see MQRC_NOT_AUTHORIZED (reason 2035), check that the JMS connection factory or Traffic Parrot Send/Receive configuration uses app with an empty password, not admin. Production hardening for the developer image is out of scope — for production deployments follow the official IBM® MQ security documentation.

Out of disk space on EC2 free tier

AWS free tier instances ship with a small EBS volume (typically 8 GB). The IBM® MQ image plus pulled layers consume a meaningful slice of that. If docker pull or docker run fails with no space left on device, run df -h to confirm and then sudo docker system prune -a to reclaim unused images and stopped containers. If you still need more headroom, extend the EBS volume from the AWS console and grow the filesystem with sudo growpart /dev/xvda 1 and sudo xfs_growfs -d /.

Continue with Chapter 4: Mocking and simulating JMS IBM® WebSphere MQ to use this Docker IBM® MQ for service virtualization, or browse the Traffic Parrot JMS documentation.