0 0 Share PDF

IBM MQ and WebSphere Liberty for Docker Enterprise Edition 17.06

Article ID: KB000785

Overview

This Solution Brief illustrates how Docker Enterprise Edition, Universal Control Plane (UCP), and Docker Trusted Registry (DTR), is used to stand up a topology with IBM MQ communicating between two applications running on separate instances of WebSphere Liberty.

Information on IBM MQ and WebSphere Liberty is provided by Docker as a known, working configuration at the time of publishing. Docker does not support IBM MQ or WebSphere Liberty. Please contact IBM Support if you have any questions or problems with them.

IBM MQ Overview

IBM MQ (often referred to as "MQ") is IBM's Messaging solution for Enterprise and IBM's Message Oriented Middleware offering. It allows independent applications to securely communicate with each other across multiple different systems. WebSphere Application Server provides flexible and secure runtimes for mission-critical Java enterprise applications, lightweight web applications, and micro services.

These two products are often found in enterprise IT deployments. MQ is used to securely communicate between applications running in WebSphere Liberty servers.

Architecture

MQ-Liberty Architecture

This deployment shows:

  1. MQ and two Websphere Liberty servers are deployed on Docker for Mac or Docker Enterprise Edition. A "sender" Java application is deployed and managed by one Liberty server. A "receiver" application is deployed and managed by the other.
  2. After the containers are started, the sender application creates a connection to the queue manager (QM1). The sender application puts a message on the queue (Q1).
  3. The sender application then waits for a response from the receiver.
  4. The receiver application continuously monitors the queue for messages using a message-driven bean.
  5. The receiving application consumes the message from the queue and creates a response.
  6. The receiving application puts the response on a temporary response queue and closes the connection to the queue.
  7. The sending application then sees the message and consumes it from the queue.
  8. The sending application reports its progress back to the browser and writes the same messages out to the logs.

Prerequisites

The following are prerequisites for installing IBM MQ and WebSphere Liberty:

Installation and Configuration (Docker for Mac)

Use the following steps to install and configure IBM MQ and WebSphere Liberty:

  1. Install the git utility if not already installed.

  2. In a terminal window, navigate to the folder you would like to place the repository (or create a new one), then run the command:

    $ git clone https://github.com/WASdev/sample.docker.mq.git
    
  3. MQ requires a resource adapter that allows WebSphere Liberty to connect to IBM MQ to enable it to send messages to a second web application. The MQ resource adapter is available through the IBM Fix Central page or from the MQ installation. To locate a version that is available for download, unblock any popups from IBM, and search for the term "InstallRA" from the search box provided. The name of the file to be downloaded is in the format of <V.R.M.F>-IBM-MQ-Java-InstallRA.jar.

  4. Click through the selection and agreement forms. Download the most recent resource adapter. (This guide was tested with version 9.0.5.0.)

  5. Put the resource adapter JAR file that you downloaded into both the liberty-sender and liberty-receiver application folders found in ./sample.docker.mq.

  6. Edit the Dockerfile in both liberty-sender and liberty-receiver:

    1. Change to the Docker Store version of the WebSphere Liberty (replace FROM websphere-liberty with FROM store/ibmcorp/websphere-liberty:webProfile7).
    2. Ensure that the COPY commands for the resource adapter is up-to-date with the current resource adapter’s version (e.g. change 9.0.0.0 to 9.0.5.0 in two places).
    3. (Optional) To enable the WebSphere Admin Center console, paste this Run statement to the bottom of each of the Dockerfiles:
    RUN mkdir -p /config/configDropins/overrides/ \ && echo '<server>\
    <featureManager><feature>adminCenter-1.0</feature></featureManager>\
    <quickStartSecurity userName="wsadmin" userPassword="wsadmin"></quickStartSecurity>\
    <remoteFileAccess><writeDir>${server.config.dir}</writeDir></remoteFileAccess>\
    </server>' > /config/configDropins/overrides/adminCenter.xml \ && installUtility install --acceptLicense defaultServer
    
  7. Navigate to the mq directory under ./sample.docker.mq and edit the Dockerfile.

    Replace FROM ibmcom/mq with FROM store/ibmcorp/mqadvanced-server-dev:9.0.3.

  8. In the ./sample.docker.mq directory, edit the docker-compose.yml file, and replace the entire contents with the following commands. Make sure that the indentation of the text is preserved.

        version: '3'
        services:
      mqfull:
        build: mq
        environment:
          LICENSE: accept
          MQ_QMGR_NAME: QM1
        # MQSNOAUT - This environment variable disables all authorization checking in MQ.
        # This is not recommended for production environments
          MQSNOAUT: "yes"
        ports:
          - "1414:1414"
          - "9443:9443"
      sender:
        build: liberty-sender
        ports:
          - "10080:9080"
          - "10443:9443"
      receiver:
        build: liberty-receiver
        ports:
          - "10081:9080"
          - "10444:9443"
    
  9. In a browser and using a previously created Docker ID, log into Docker Store. Subscribe to both the Websphere Liberty and MQ Advanced images. These images are free. Here are the example steps to subscribe to the Websphere Liberty image. Follow the same process for the MQ Advanced image.

    Websphere Store Page Subscription Screen: Websphere Content

  10. Execute:

    $ chmod 755 build
    $ ./build
    

    This uses maven to build the WAR files for both of the applications in the sender and receiver directories and makes sure they are put in the correct locations. This will take several minutes.

  11. (Optional) To ensure a stable build environment, make sure that any stopped containers and layers have been cleaned up.

    $ docker system prune
    ...
    

Verifying the Deployment (Docker for Mac)

To verify the deployment, simply execute:

$ docker-compose up --build

This confirms the successful build and bring up three containers: mqfull, liberty-server, and liberty-receiver. A docker ps will look something like this:

$ docker ps
CONTAINER ID        IMAGE                     COMMAND                  CREATED             STATUS              PORTS                                              NAMES
b354b1cb9ab2        sampledockermq_sender     "/opt/ibm/docker/doc…"   2 minutes ago       Up 2 minutes        0.0.0.0:10080->9080/tcp, 0.0.0.0:10443->9443/tcp   sampledockermq_sender_1
74f1270faae6        sampledockermq_mqfull     "mq.sh"                  2 minutes ago       Up 2 minutes        0.0.0.0:1414->1414/tcp, 0.0.0.0:9443->9443/tcp     sampledockermq_mqfull_1
9cf7f1e9c5bc        sampledockermq_receiver   "/opt/ibm/docker/doc…"   2 minutes ago       Up 2 minutes        0.0.0.0:10081->9080/tcp, 0.0.0.0:10444->9443/tcp   sampledockermq_receiver_1

You can now access the application, the MQ Console, and the two Liberty servers:

  • Application: http://localhost:10080/sender/

    Port 10080 Sender Receiver

    Output to log files upon refresh of browser http://localhost:10080/sender/

    sender_1    | > Results:
    sender_1    | > Creating connection to QueueManager
    sender_1    | > Sending message request of 'Give me something back receiver'
    sender_1    | > Sent Message ID=ID:414d5120514d31202020202020202020d331a85acc099921
    sender_1    | > Waiting for response
    receiver_1  | Message Received!!!
    receiver_1  | Sending reply
    receiver_1  | Closing connection
    sender_1    | > Received Message ID=ID:414d5120514d31202020202020202020d331a85acc0c9921 for 'Here is your response sender'
    sender_1    | > Closing Connection
    
  • MQ Console: https://localhost:9443/ibmmq/console/login.html (admin/passw0rd)

    Port 9443 MQ Console

  • liberty-sender is at https://localhost:10443/adminCenter/login.jsp (wsadmin/wsadmin); likewise, liberty-receiver is at https://localhost:10444/adminCenter/login.jsp.

    Port 10443 Sender Console Port 10444 Receiver Console

Stopping the Application (Docker for Mac)

To stop the application, execute:

$ docker-compose down
...
Removing sampledockermq_sender_1   ... done
Removing sampledockermq_mqfull_1   ... done
Removing sampledockermq_receiver_1 ... done

Configuration and Deployment (Docker Enterprise Edition)

To deploy IBM MQ and WebSphere Liberty on Docker Enterprise Edition 17.06, begin with the provisioning of an appropriate number of instances for site-specific performance and high availability.

EE MQ-Liberty Architecture

In this example, a four instance deployment was provisioned consisting of one instance for UCP Management and three instances to run each of the three worker containers: MQ, Sender, and Receiver. Docker Trusted Registry (DTR) is also installed on the instance with one of the worker containers. This guide assumes that UCP and DTR have been installed and configured and that access to the "admin" account and password have been provided.

Move Images to Docker EE

Since the original MQ and Liberty images have been extended during the build process, these extended images must be tagged and pushed into the cloud service provider environment. This can be done by pushing the local images to DTR and then altering the docker-compose.yml so that it points to these images.

  1. Log into DTR (https://{dtr-registry-address}) as "admin" and click on the New repository button towards the upper right portion of the window.

  2. In the field REPOSITORY NAME, enter test-mq and then click on Save towards the bottom right of the window.

  3. Create two more repositories named test-sender and test-receiver. Log out of DTR.

  4. From a new terminal window on Docker for Mac/Linux, execute:

    $ docker login {dtr-registry-address}
    
  5. When prompted, enter "admin" as the username and then the appropriate password.

  6. Prepare the images created in the previous steps for the Docker Trusted Registry:

    $ docker tag sampledockermq_mqfull {dtr-registry-address}/admin/test-mq:1.0
    $ docker tag sampledockermq_sender {dtr-registry-address}/admin/test-sender:1.0
    $ docker tag sampledockermq_receiver {dtr-registry-address}/admin/test-receiver:1.0
    
  7. Push images to the Docker Trusted Registry:

    $ docker push {dtr-registry-address}/admin/test-mq:1.0
    ...
    $ docker push {dtr-registry-address}/admin/test-sender:1.0
    ...
    $ docker push {dtr-registry-address}/admin/test-receiver:1.0
    ...
    

    Use an edited version docker-compose.yml file to run the MQ-Liberty Solution directly from UCP.

  8. Copy the docker-compose.yml commands below into a text or code editor:

        version: '3'
        services:
      mqfull:
        image: {dtr-registry-address}/admin/test-mq:1.0
        environment:
          LICENSE: accept
          MQ_QMGR_NAME: QM1
          MQSNOAUT: "yes"
          # Do not use MQSNOAUT for secure environments
        ports:
          - "1414:1414"
          - "9443:9443"
      sender:
        image: {dtr-registry-address}/admin/test-sender:1.0
        ports:
          - "10080:9080"
          - "10443:9443"
      receiver:
        image: {dtr-registry-address}/admin/test-receiver:1.0
        ports:
         - "10081:9080"
         - "10444:9443"
    
  9. Change the {dtr-registry-address} fields with the URL appropriate for the installation of DTR.

  10. Copy the entire contents into the clipboard. Be sure to preserve indentation layout.

  11. Access the URL for the UCP management node and login as "admin".

  12. Click on Stacks in the left sidebar:

    UCP Screen1

  13. Click on Create Stack in the upper right of window:

    UCP Screen2

  14. On the Create Stack screen, provide a Stack Name and Mode (Choose Services). Paste the edited docker-compose.yml commands from the clipboard with the appropriate address for DTR Registry.

  15. Finally, click on the Create button to deploy the stack:

    UCP Screen3

Verifying the Deployment (Docker EE)

  • To verify that the containers launched successfully, click on Services in the left sidebar on the UCP home screen The mqfull, liberty-sender, and liberty-receiver show with green status and no errors.

    UCP Deploy

  • To verify that it is functioning correctly, connect to http://{ucp-ip-address}:10080/sender/. After each screen refresh, the sender will post a message to receiver. Receiver will answer with a message back.

    Sender-Receiver from UCP

  • To bring down the solution, click on Stacks in the left sidebar and then click on the "Name" of the stack. A menu bar will appear on the right. Click on Remove to stop and remove the containers:

    Stop Containers

Troubleshooting

If errors occur in the build or the sender/receiver communication, it may be necessary to re-build after removing all images and clearing cashes. This can be achieved using the following commands:

$ docker-compose rm
...
$ docker system prune
...

Further Reading

Refer to the following links for additional information: