Skip to content

Labs

Jump to bottom Edit New page
jamiecoleman92 edited this page Feb 29, 2016 · 2 revisions

Session: 2341

Hands on with WAS Liberty under Docker and IBM Containers

Lab Instructions

Authors: David Currie, Senior Software Engineer, david_currie@uk.ibm.com

February 2016 edition NOTICES This information was developed for products and services offered in the USA. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive, MD-NC119 Armonk, NY 10504-1785 United States of America The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM websites are provided for convenience only and do not in any manner serve as an endorsement of those websites. The materials at those websites are not part of the materials for this IBM product and use of those websites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. TRADEMARKS IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the web at “Copyright and trademark information” at www.ibm.com/legal/copytrade.shtml. Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other countries, or both and is used under license therefrom. Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. IT Infrastructure Library is a Registered Trade Mark of AXELOS Limited. ITIL is a Registered Trade Mark of AXELOS Limited. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. Linear Tape-Open, LTO, the LTO Logo, Ultrium, and the Ultrium logo are trademarks of HP, IBM Corp. and Quantum in the U.S. and other countries. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. © Copyright International Business Machines Corporation 2015. This document may not be reproduced in whole or in part without the prior written permission of IBM. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Resource guide IBM Technical Client Training has enhanced its training capabilities, and extended reach into new cities and countries, by partnering with five highly qualified IBM Business Partners who provide high quality, authorized training for IBM Clients, IBM Business Partners, and IBM employees. IBM continues to provide authorized training curriculum and content, and also maintains overall ownership of the IBM Training ecosystem. The delivery of public, private and customized training to IBM Clients and IBM Business Partners is now done by the IBM Global Training Providers (GTPs): • Arrow • Avnet • Global Knowledge • Ingram Micro • LearnQuest See ibm.com/training for information on the classes that the GTPs offer. Completing this InterConnect lab is a great first step in building your IBM skills. IBM offers several resources to keep your skills on the cutting edge. Resources available to you range from product documentation to support websites and social media websites, including the following examples: • IBM Training website – Bookmark the IBM Training website for easy access to the full listing of IBM training curricula. The website also features training paths to help you select your next course and available certifications. – For more information, see http://www.ibm.com/training • IBM Certification – Demonstrate your mastery of IBM products to your employer or clients through IBM Professional Certification. Certifications are available for developers, administrators, and business analysts. – For more information, see http://www.ibm.com/certify Introduction Although Docker is being ported to other platforms, in its original form it runs natively on Linux us-ing capabilities provided by the Linux kernel. When using Docker in a Windows or OS/X develop-ment environment it is typical to install the Docker Toolbox (https://www.docker.com/docker-toolbox) which provides the Docker command line running natively, talking to the Docker engine running in a lightweight Linux Virtual Box virtual machine. Prerequisites: • DockerToolbox 1.10.2 for Windows & Mac/Docker & Docker Compose for Linux https://www.docker.com/products/docker-toolbox/ https://docs.docker.com/engine/installation/linux/ubuntulinux/ • Cloud Foundry CLI 6.14.0 and the IBM Containers plug-in 0.8.788 https://console.ng.bluemix.net/docs/containers/container_cli_cfic.html To complete the final section of this lab you will need an IBM ID registered with IBM Bluemix. If you do not have an IBM ID, or have not signed up for Bluemix, and wish to complete this section of the lab then sign up for a free 30-day trial at https://console.ng.bluemix.net/registration/. It is recommended that you do this before starting the lab to ensure that you have time for the registra-tion process to complete. Running a Liberty container In this section you’ll run your first Liberty server under Docker using the websphere-liberty image that is available from the online Docker Hub repository of images.

  1. Open the Docker Quickstart Terminal or just a normal Terminal on Windows.
  2. Populate the local image cache with WebSphere-Liberty by using the following command to pull it down from Docker Hub: $ docker pull websphere-liberty

This will pull down the layers that make up the image. The total image size, including the base Ubuntu image on which it builds, is around 570MB. Depending on the layers that have changed since the cache was populated it may therefore take several minutes to download the latest version. 3. Execute the following command to see the layers that make up the Liberty image: $ docker history websphere-liberty

The layers represent the commands that were issued when the image was built (specify the –no-trunc option if you want to see the full commands). The bottom four layers represent the ‘ubuntu’ image that you saw earlier. After setting the maintainer and installing wget, the Dockerfile downloads and installs an IBM JRE and the WebSphere Liberty kernel. It then creates a server and then sets the metadata around the image such as the ports to expose and the command to run. It then adds additional features using the installUtility command to build up to the full set of Java EE7 features.

  1. You can see the total size of the image by running the command: $ docker images websphere-liberty

  2. Run the image with the following command (the ‘-i' and ‘-t’ options specify that an interactive terminal is required): $ docker run –i -t websphere-liberty

  3. The server isn’t much use though as we didn’t expose any ports to access it. Type ‘Ctrl-C’ to stop the server. (If you failed to specify the ‘-i –t’ options then you will have to kill the process from another terminal.)

  4. This time map the port 9080 from the container to port 80 on the host VM: $ docker run -d -p 80:9080 --name wlp websphere-liberty

Note that this time you have specified the ‘-d’ option to run the container in the background, and we have given it a name so that we can subsequently refer to it by this name rather than using the generated name or id.

  1. Use the following command to follow the logs of the container as it starts up: $ docker logs --tail=all -f wlp

Once the server is ready to run, type ‘Ctrl-C’ to return to the command prompt.

  1. Open Firefox at ‘localhost’ to view the Liberty welcome page.

  2. Return to the terminal and enter the following command to see the processes running in the container: $ docker top wlp

You will see the ‘server’ script and the child Java process.

  1. If you execute the following command, you can see that these processes can also be seen at the level of the Docker host. They are normal Linux processes whose visibility of the rest of the host are constrained by the use of Linux namespaces. $ ps aux | grep wlp

  2. Docker permits us to run other processes inside the namespaces of an existing container. This is primarily used for diagnostic purposes. a. For example, type the following command to start an interactive session inside the running container: $ docker exec -it wlp bash

You will see the command prompt change indicating that you are now running as the root user within the container.

b. Execute the following command to show all of the processes running within the container namespace.

ps aux

Note that within the container you do not have visibility of other processes running on the host.

c. Execute the following command inside the container to view the contents of the server log file:

cat /logs/messages.log

d. Enter the following command to end the terminal session. The container will continue to run.

exit

  1. It is also possible to copy files out of the container. a. For example type the following command to copy the messages.log file from the container ‘wlp’ to the current directory: $ docker cp wlp:/logs/messages.log . b. Then run execute the following command to view the file: $ cat messages.log
  2. Finally, run the following commands to clear up the container: $ docker stop wlp $ docker rm wlp

Handling multiple containers Explicitly setting ports and names is fine if you only have a single container but what if you are trying to run multiple instances of an image?

  1. Type the following command to run the Liberty image again: $ C=$(docker run -d -P websphere-liberty)

This time you have specified the ‘-P’ flag to indicate that Docker should automatically select ports on the host to map those exposed by the image to. You have also saved the identifier for the new container in the variable ‘$C’. 2. Run the following command to see the ports on the host that Docker has mapped 9080 and 9443 to: $ docker ps

  1. The ‘docker port’ command can be used to retrieve the mapping for a specific port. For example, you can retrieve the Liberty welcome page for this container by typing the command: $ curl $(docker port $C 9080)

  2. Using ‘docker inspect $C’ reveals lots more interesting information about the running container. The command accepts filters in the golang template format so, for example, it is possible to retrieve just the IP address for the container using: $ docker inspect --format '{{ .NetworkSettings.IPAddress }}' $C

  3. You can now run another instance of the container using the same command and Docker will allocate different ports: $ D=$(docker run -d -P websphere-liberty)

  4. Execute the following command to confirm that you now have two containers running: $ docker ps

  5. Run the following command to see a live stream of stats from the running containers: $ docker stats $C $D

Note that, having not expressed any constraints, each container has the full 2GB memory allocation to it.

  1. Enter ‘Ctrl-C’ to terminate the stats stream.
  2. Clean up the containers with the following commands: $ docker kill $C $D $ docker rm $(docker ps -aq) Adding an application You now know how to run one or more Liberty servers under Docker – next you need to add an application to the mix. There are a number of different approaches to running an application on the Liberty Docker Hub image which you’ll explore in this section of the lab. Mounting an application on the image The first method is simply to mount an application or directory from the host when the container is started.
  3. Change down in to the ‘app’ directory of the lab materials: $ cd Desktop/materials/app
  4. Use the following command to run a container with WebSphere Liberty: $ docker run -d -p 80:9080 --name=app
    -v $(pwd)/ServletApp.war:/config/dropins/app.war
    websphere-liberty

The important part of the command is the ‘-v’ option which indicates that the ServletApp.war from the current directory (Docker requires an absolute path) should be mounted in to the dropins directory of the Liberty configuration.

  1. Use the following command to watch the server start: $ docker logs --tail=all -f app

You should see log entries indicating that the application has been started.

  1. View it in the Firefox browser at ‘http://localhost/app’.

  2. Clean up the server with the following commands: $ docker kill app $ docker rm app Creating an application layer The approach above is fine for development purposes allowing you to rapidly update the applica-tion but mounting a file from the host breaks the portability that is often a driver to use Docker in the first place. The next approach is to build an image with the application contained within a lay-er.

  3. In the current directory, list the contents of ‘Dockerfile’ with the following command: $ cat Dockerfile

It simply starts from the websphere-liberty image and adds the ServletApp.war from the current directory in to the dropins directory.

  1. Build an image tagged ‘app’ using the current directory as context using the command: $ docker build -t app .

  2. To run the new built image, use the command: docker run -d -p 80:9080 --name=app app

  3. Repeat steps 3-5 from the previous section to watch the server start, verify that it is running, and then clean up. Using a data volume container The approach from the previous section means that you have neatly packaged a single image that contains everything needed to run the application. It does, however, mean that if we want to move up to a new version of the Liberty image we have to rebuild our application as well. The fol-lowing approach using a data volume container to separate the application and the server runtime in two separate images.

  4. Run the image that you created in the previous section with the following command: $ docker run -v /config --name=app app true

This time, the ‘-v’ flag is being use to export a volume from the server. The last parameter of ‘true’ is the command that the container will run. This will exit immediately leaving you with a stopped container that exposes the server configuration containing the application.

Note:  You have just reused the existing image for convenience here. You are not going to use the Liberty server runtime in it and could equally have used an image created from ‘ubuntu’. 2. Now run the following command to start a Liberty container: $ docker run --volumes-from app -d -p 80:9080 websphere-liberty

The key option this time is the ‘--volumes-from’ flag which indicates that the volumes exported by the container ‘app’ should be mounted on this container. 3. Once again, use the following command to watch the server start (where he ‘docker ps -lq' command returns the ID of the last container run): $ docker logs --tail=all -f $(docker ps –lq)

You should see log entries indicating that the application has been started.

  1. View the web app in the browser at ‘http://localhost/app’.

  2. Clean up the server and the two containers with the following commands: $ docker kill $(docker ps -lq) $ docker rm $(docker ps -aq)

  3. Remove the application image with the command: $ docker rmi app Running dependencies in containers Another usage pattern for Docker is to package not only the application, but also its dependencies in to Docker containers. In this section you’ll run the Liberty MongoDB sample in one container with MongoDB running in another and then use Docker Compose to manage them both. Resolving dependencies via linking You’ll begin by using Docker linking to allow the Liberty application to resolve the MongoDB in-stance.

  4. Create an image with WebSphere Liberty and the MongoDB feature as follows. a. Switch to the ‘mongo’ directory by typing: $ cd ../ mongo b. View the contents of the Dockerfile by typing: $ cat Dockerfile

The file adds the Liberty mongodb-2.0 feature from the Liberty online repository using the ‘installUtility’ command and then copies in the server configuration.

  1. View the server.xml by running: $ cat mongoDBSample/server.xml

The important part to note is the stanza that specifies that the hostname should be ‘db’.

  1. Build the application with the command: $ docker build -t app .

  2. Pull down MongoDB from DockerHub to your local cache using the command: $ docker pull mongodb

  3. Now start the MongoDB server using the following command: $ docker run -d --name mongodb mongo

  4. Now start an instance of the app container using the following command: $ docker run -d --link mongodb:db -p 80:9080 --name app app

The ‘--link' option indicates that the ‘mongodb’ container should be made available to this container under the alias ‘db’. This means that ‘/etc/hosts’ will be updated to resolve ‘db’ to the IP for the ‘mongodb’ container. 7. Use the following command to wait for the server to start: $ docker logs --tail=all -f app 8. Browse to ‘http://localhost/mongoDBApp’. Each time the page is refreshed it writes more users in to the MongoDB base.

  1. Clean up the containers and images with the following commands: $ docker kill $(docker ps -aq) $ docker rm $(docker ps -aq) $ docker rmi app

Note:  Container linking only works between containers on a single host. Across multiple hosts there are a number of options:

  1. Pass the address of the remote container as an environment variable to the container. The Liberty ‘$(env.XXX)’ syntax makes it easy to substitute variables in to server.xml.
  2. Use some form of service registry to locate dependencies (e.g. etcd, consul, …).
  3. Use a Docker overlay network to create a software defined network spanning the multiple hosts. Docker Compose for container orchestration Docker Compose provides a simple format to define the relationship between containers that de-fine a single application.
  4. View the docker-compose.yml in the current directory that defines the application using: $ cat docker-compose.yml

Note that it defines two services: web and db and links them together.

  1. Start the application with the following command (as with the ‘docker’ command, the ‘-d’ option starts the containers in the background): $ docker-compose up -d

  2. The following command will then show an aggregated view of the logs from the two services: $ docker-compose logs

  3. Ctrl-C to exit the logs view.

  4. You can scale up the number of containers for the web service using the command: $ docker-compose scale web=2

  5. Use the following command to list all of the containers that make up the application: $ docker-compose ps

  6. Execute the following commands to demonstrate that the two Liberty containers are using the same MongoDB instance: $ curl $(docker-compose port --index=1 web 9080)/mongoDBApp $ curl $(docker-compose port --index=2 web 9080)/mongoDBApp

You should see that the two web app instances are serving data from the same MongoDB database with the second command returning the users created by the first command plus ten more. 8. Clean up the containers with the following commands: $ docker-compose kill $ docker-compose rm -f

Note:  Docker Compose can only communicate with a single Docker API endpoint and therefore, by default, is restricted to creating containers on a single node. However, when used in conjunction with Docker Swarm, which exposes a single API endpoint for managing a cluster of Docker nodes, it becomes much more powerful. Deploying to IBM Containers In this last section, you’ll deploy the same Liberty MongoDB sample to the IBM Containers service on IBM Bluemix.

  1. Log in IBM Bluemix using the Cloud Foundry CLI. You will be prompted to provide your IBM ID and password. $ cf login -a https://api.ng.bluemix.net
  2. If you haven’t use IBM Containers before, you need to specify a Docker registry namespace to use with your account. $ cf ic namespace set
  3. Initialize the IBM Containers plugin: $ cf ic init

Note:  When the init command is run you will be presented with two options. Option one allows you to simultaneously manage IBM Containers and your local Docker host through “cf ic” commands. Option two uses the Docker CLI, overriding the local Docker environment to connect to IBM Containers. This tutorial will use the first option.
4. Copy the MongoDB Docker Hub image to your Bluemix registry. $ cf ic cpi mongo registry.ng.bluemix.net//mongo

  1. Run an instance of the Mongo image that you just copied across called mongodb $ cf ic run -d --name mongodb \ registry.ng.bluemix.net//mongo

  2. Change to the ‘bluemix’ directory in the materials folder. $ cd ../bluemix/

  3. You could re-use the existing ‘app’ image that you built earlier but it is quicker to rebuild the image in IBM Bluemix than upload it. Look at the Dockerfile using the following com-mand. Notice the base image being used is the ibmliberty image in the IBM Containers registry. $ cat Dockerfile

  4. Build the app in IBM Bluemix: $ cf ic build -t registry.ng.bluemix.net//app .

  5. Run the app that you just built linking the mongodb app as you did previously. $ cf ic run -d --link mongodb:db -p 80:9080 --name app
    registry.ng.bluemix.net//app

  6. Check all the containers are up and running: $ cf ic ps

  7. Access the application using the allocated IP address. $ curl $(cf ic port app 9080)/mongoDBApp

  8. Clean up the containers and images with the following commands: $ cf ic kill $(cf ic ps -aq) $ cf ic rm $(cf ic ps -aq) $ cf ic rmi registry.ng.bluemix.net//app $ cf ic rmi registry.ng.bluemix.net//mongo Congratulations Congratulations! You have completed this lab. You now know how to build a Docker image con-taining WebSphere Liberty and your application and run it locally or on the IBM Containers service on IBM Bluemix.

lolo

MQ Docker Repo

Clone this wiki locally