This tutorial demonstrates how easy it is to set up a connection between two instances of WebSphere Liberty using IBM MQ as the messaging service, all running under Docker containers. This is done using Docker Compose which brings up the containers and connects them to one another.
Before you start
This has been tested on Docker Machine, Ubuntu 15.10 and Fedora 23 so take your pick.
- Install Docker.
- Install Docker Compose.
- Install Git.
- Upgrade the Linux Kernel to V3.16 minimum.
- Complete the prerequisites for MQ. On Docker Machine and most Linux distributions, simply
sshinto the host and run the command:
sudo sysctl fs.file-max=524288. This will increase the maximum file limit for the current session.
Preparing the Web applications
- Clone the repository from GitHub to your local machine. If you are on Windows/Mac, open up the Docker Quickstart Terminal; on Linux just open up a normal terminal. Navigate to the folder you would like the repository to be pulled into then run the following command:
git clone https://github.com/WASdev/sample.docker.mq.git
- Download the resource adapter for MQ. This allows WebSphere Liberty to connect to IBM MQ in order to send messages to a second web application. You can find the resource adapter for MQ on the IBM Fix Central page. To locate the latest version that is available for download, enter the phrase
Resource Adapterin the Search Fix Central box (alternatively, select IBM MQ from the Product selector list, then select 9.0 and Linux 64-bit,x86_64, then browse for fixes and the resource adapter should be one of the fixes displayed). The name of the file to be downloaded is in the format of
- Put the resource adapter JAR file that you downloaded in the application folders that were downloaded into your local repository from GitHub
- Open the Dockerfile for each application and check that the line for copying the resource adapter in to the image is up-to-date with the current resource adapter’s name.
./buildwhich uses maven to build the WAR files for the two applications in the
receiverdirectories and copies them in to the correct locations.
Deploying the Web applications
This part of the tutorial is very simple because Docker Compose does most of the work for you. Simply navigate to the root of the repository that you downloaded from GitHub and run:
This will build and then start the Docker images for both instances of Liberty and IBM MQ. The second Liberty container has a message-driven bean so, if it starts before IBM MQ, it will throw some errors in the logs because it has no queue to listen on. As soon as MQ is available the message-driven bean will connect.
What Docker Compose is doing when deploying your containers
docker-compose.yml file is used for building the images, setting environment variables, exposing ports, accepting the license agreement for MQ and linking the containers to one another.
mq: build: mq environment: LICENSE: accept MQ_QMGR_NAME: QM1 ports: - "1414:1414" sender: build: liberty-sender links: - mq:mqfull ports: - "9080" - "9443" receiver: build: liberty-receiver links: - mq:mqfull ports: - "9080" - "9443"
For the instances of our Web application and server, Docker Compose is building the images using the Dockerfiles inside the application folders.
FROM websphere-liberty MAINTAINER Jamie Coleman <firstname.lastname@example.org> COPY server.xml /opt/ibm/wlp/usr/servers/defaultServer/ COPY 188.8.131.52-IBM-MQ-Java-InstallRA.jar / COPY sender.war /opt/ibm/wlp/usr/servers/defaultServer/dropins/ RUN installUtility install --acceptLicense defaultServer RUN java -jar 184.108.40.206-IBM-MQ-Java-InstallRA.jar --acceptLicense /
FROMline (line 1) gets the standard Liberty Docker image from Docker Hub.
- The first
COPYline (line 6) copies the resource adapter to the container that is needed to establish a connection to IBM MQ.
- The second
COPYline (line 7) copies the Web application to the container.
- The first
RUNcommand (line 9) installs the features that Liberty needs for this tutorial. You can find more explanation of these features in the
server.xmlsection of this tutorial.
- The second
RUNcommand (line 10) accepts the license agreement and installs the resource adapter.
For our instance of IBM MQ, Docker Compose builds the image from the Dockerfile located in the
mq directory. This Dockerfile pulls down the MQ image from Docker Hub and copies the
config.mqsc file in to the image. The Dockerfile contents are shown below.
FROM ibmimages/mqadvanced COPY config.mqsc /etc/mqm/
config.mqsc file defines the necessary channels and queues we need. Note that, for the purposes of this tutorial, the file disables security which would not be recommended in a production scenario.
Running the Application
This is a relatively easy task. You just need to navigate to the URL provided for your first Liberty container. You can find this URL by running the command:
docker-compose port sender 9080
If you’re running on Docker Machine, you need to either forward your ports or use
docker-machine ip to find the IP address of your Docker host. The URL should look something like this:
0.0.0.0:xxxx/sender/ or 192.xxx.xxx.xxx:xxxx/sender/
What the applications are doing
- The sending application uses a connection factory and destination bound in to JNDI.
- When the servlet is accessing, the sending application creates a connection to the queue manager (
- The sending application puts a message on the queue (
- The sending application then waits for a response.
- The receiving application is constantly monitoring the queue for messages using a message-driven bean.
- The receiving application consumes the message from the queue and creates a response.
- The receiving application puts the response on a temporary response queue and closes the connection to the queue.
- The sending application then sees the message and consumes it from the queue.
- The sending application closes the connection to the queue manager until the servlet is accessed again.
The sending application reports its progress back to the browser and writes the same messages out to the logs.
Congratulations – you have successfully deployed two applications running on Liberty to communicate via IBM MQ using just a single Docker Compose command!