Contents


Expose APIs in a WebSphere Liberty collective

Examples with four runtime environments

Comments

In today's fast changing and demanding microservices world, developers need to be flexible and agile in terms of their runtime deployments. A traditional development shop now uses a variety of runtime environments. The two most popular are Java and Node.js, sometimes inside a container (Docker).

Developers need a way to expose these diverse business assets as APIs, so that they can be consumed by a variety of clients, including mobile devices. The challenge is that each of these environments expose APIs individually and somewhat differently, making it hard for potential consumers (both internal and external to your organization) to discover the full set of available assets.

With IBM® WebSphere® Application Server Liberty, you can use collectives to organize servers to deliver application services to your application efficiently. You can organize Liberty servers into collectives to support clustering, administration, and other operations that act on multiple Liberty servers.

With enhancements in WebSphere Liberty 17.0.0.1, you can create a Liberty collective environment to deploy and manage hybrid workloads. Liberty 17.0.0.1 supports Java, Node.js, WebSphere Liberty in Docker and Node.js in Docker, with a framework that consistently aggregates available APIs into one catalog. Consumers of the APIs now have one place to view and invoke all the business assets in a Liberty collective, regardless of how each is implemented. And API developers have freedom to modify implementations, such as switching from Node.js to Java, without disrupting the API clients.

This tutorial demonstrates how to expose APIs for these four different runtime environments that you and other developers can view in a browser, listed in a WebSphere Liberty collective explorer.

You learn how to create a Liberty collective environment with WebSphere Liberty, Node.js, Node.js in Docker, and WebSphere Liberty in Docker members. Then you learn to expose the APIs in a collective API explorer, based on OpenAPI and Swagger.

You can deploy members of a collective by using the WebSphere Liberty Admin Center or the deployment REST API. This tutorial focuses on deploying Node.js and Docker members to the collective by using the Admin Center. Next, it walks through the steps to expose the APIs.

What you need to build the environment

Note: Versions of the following features are based on WebSphere Liberty 17.0.0.1.

  • Familiarity with WebSphere Liberty, Node.js and Docker.
  • Java applications that have REST APIs to install on WebSphere Liberty and on WebSphere Liberty in Docker members.
  • Websphere Liberty 17.0.0.1 installed on a machine for a collective controller, which allows a server to become the controller for a management collective. See Get started with Liberty.
    The following features should be installed for the controller machine:
  • Websphere Liberty 17.0.0.1 installed on another machine for WebSphere Liberty members. All features that you need for your Java application should be installed, such as the following example:
	<featureManager>
		<feature>collectiveMember-1.0</feature>
		<feature>clusterMember-1.0</feature>
		<feature>apiDiscovery-1.0</feature>
		<feature>localConnector-1.0</feature>
		<feature>ejbLite-3.2</feature>
		<feature>jsf-2.2</feature>
		<feature>jaxws-2.2</feature>
		<feature>websocket-1.1</feature>
		<feature>jdbc-4.1</feature>
		<feature>cdi-1.2</feature>
		<feature>jsp-2.3</feature>
		<feature>jpa-2.1</feature>
		<feature>jaxrs-2.0</feature>
		<feature>jndi-1.0</feature>
		<feature>beanValidation-1.1</feature>
		<feature>ldapRegistry-3.0</feature>
	</featureManager>
  • Docker installed on a machine for Docker members. See Get Docker for Red Hat Enterprise Linux . (Note: The command examples in this tutorial for Node.js and Docker machines use Red Hat Enterprise Linux 7.)
  • Node.js V4.7.3 installed on a machine for a Node.js member.

To install Node.js V4.7.3, complete the following steps:

  1. Download node-v4.7.3-linux-x64.tar.gz from https://nodejs.org:
     		# wget https://nodejs.org/dist/v4.7.3/node-v4.7.3-linux-x64.tar.gz
  2. Extract the node-v4.7.3-linux-x64.tar.gz file to /usr/local with the following commands:
    		# cd /usr/local
    		# tar --strip-components 1 -xzf <path>/node-v4.7.3-linux-x64.tar.gz
  3. Install npm, node-gyp-install, apic, and apiconnect-collective-member with the following commands:
    		# cd /root
    		# npm  install -g npm
    		# npm install -g node-gyp-install
    		# npm cache clear
    		# npm install -g apiconnect-collective-member
    		# npm install -g apiconnect
  4. Check the /usr/local/bin directory to see the installation of node.js, npm and apiconnect-collective-member with the following commands:
    		# ls -l /usr/local/bin
    		total 24252
    		lrwxrwxrwx 1 root root       41 Feb 22 18:17 apic -> ../lib/node_modules/apiconnect/bin/cli.js
    		-rwxrwxr-x 1  500  500 24830187 Jan 31 16:05 node
    		lrwxrwxrwx 1 root root       43 Feb 22 18:11 node-gyp-install -> ../lib/node_modules/node-gyp-install/bin.js
    		lrwxrwxrwx 1 root root       38 Feb 22 18:10 npm -> ../lib/node_modules/npm/bin/npm-cli.js
    		lrwxrwxrwx 1 root root       60 Feb 22 18:13 wlpn -> ../lib/node_modules/apiconnect-collective-member/bin/wlpn.js
    		lrwxrwxrwx 1 root root       71 Feb 22 18:13 wlpn-collective -> ../lib/node_modules/apiconnect-collective-member/bin/wlpn-collective.js
    		lrwxrwxrwx 1 root root       67 Feb 22 18:13 wlpn-server -> ../lib/node_modules/apiconnect-collective-member/bin/wlpn-server.js
  5. Check the versions of Node.js and API Connect with the following commands:
    		# node -v
    		v4.7.3
    		# apic -v
    API Connect: v5.0.6.1 (apiconnect: v2.5.17)
  6. Check fthe versions of wlpn and wlpn-collective with the following commands:
    		# wlpn --ext-version
    		 wlpn: v2.2.1 (API Connect: v5.0.6.2)
    		 plugins 3.3.5
    		 wlpn-cli-collective 2.3.2 (8f17e4aa6a04569d2048a5200ed0c0c7779577c4)
    		 wlpn-cli-server 2.7.4 (7d16e9a47682c921cadc45b07d7c18ad4d94f0b6)
    		
    		# wlpn-collective version
    		apiconnect-collective-member: v1.5.1 (apiconnect-collective-member: v1.5.1)
1

Configure a Liberty collective

This section demonstrates how to set up a Liberty collective with the API Discovery 1.0 feature and configure a controller to customize the WebSphere Liberty collective explorer for the collective with a specific header, title and description, where you and other developers can view the exposed APIs in a browser. You can read more about these capabilities in the following blog post: new enhancements to Liberty's OpenAPI support. For more information about setting up the Liberty collective, see Configuring a Liberty collective.

  1. Create a controller with the following commands:
    	# wlp/bin/server create myController
  2. Create a keystore for secured communication between controller and its members:
    	# wlp/bin/collective create myController –keystorePassword=controllerKSPassword
  3. Follow the instructions on the console, and copy the configuration output into the controller server.xml file.
  4. Enable the following features in the server.xml file to enable the collective, the administrative center, and the API Discovery features.
    	<featureManager>
    	        <feature>collectiveController-1.0</feature>
    	        <feature>adminCenter-1.0</feature>
    	        <feature>apiDiscovery-1.0</feature>
    	 </featureManager>
  5. Specify the administrator user ID and password in <quickStartSecurity userName="adminUser" userPassword="adminPassword" /> .
  6. Add the following <apiDiscovery /> information in the controller server.xml file to customize the banner, title and description: <apiDiscovery publicURL="myPublicAPI" swaggerDefinition="${server.config.dir}/custom/swaggerDef.yaml" />

    The swaggerDefinition parameter points to the location of the Swagger definition .yaml or .json file that contains the customized title, description and banner information.

  7. Set up the swaggerDef.yaml file that step 6 references:
    1. Create a wlp/usr/server/myController/custom directory.
    2. Put the swaggerDef.yaml in the custom directory.
      See the following sample swaggerDef.yaml file. The "description":"List of available API", and the "title":"Liberty REST APIs with Custom Banner", lines are the customized information.
      		{
      		   "swagger":"2.0",
      		   "info":{
      		      "description":"List of available API",
      		      "version":"1.0.0",
      		      "title":"Liberty REST APIs with Custom Banner",
      		      "x-ibm-css":"${server.config.dir}/css/custom-header.css",
      		      "termsOfService":"http://swagger.io/terms/",
      		      "contact":{
      		         "email":"apiteam@swagger.io"
      		      },
      		      "license":{
      		         "name":"Apache 2.0",
      		         "url":"http://www.apache.org/licenses/LICENSE-2.0.html"
      		      }
      		   }
      		}
    3. Create a wlp/usr/server/myController/css directory.
    4. Put the custom-header.css file in the css directory.
      See the following sample custom-header.css file:
      		.swagger-section #header {
      		  background-image: url(images/custom-logo.png);
      		  background-repeat: no-repeat;
      		  background-position: 14px 5px;
      		  background-size: 150px 45px;
      		  background-color: #0C1F95;
      		  padding: 14px;
      		}

      The background-image has the location of the custom-logo.png file, which is a customized logo image. This tutorial uses an SVT logo, as shown in the screen capture in step 7.

    5. Create a wlp/usr/server/myController/css/images directory.
    6. Put the custom-logo.png file in the images directory.
  8. Start the controller:
    		# wlp/bin/server start myController –clean

You can download a sample WebSphere Liberty controller server.xml file from GitHub at tam512/restapi4runtimes.

2

Deploy Liberty members to the Liberty collective

This section demonstrates how to deploy two Liberty servers to the Liberty collective controller. In the following examples, a Java application named SocialSphere is installed on both Liberty members.

  1. Create two Liberty servers:
    		# wlp/bin/server create server1
    		# wlp/bin/server create server2
  2. Join the server1 to the Liberty collective:
    		# wlp/bin/collective join server1 --host=controllerHostname --port=httpsPort --user=adminUser --password=adminPassword --keystorePassword=memberKSPassword
  3. Copy and paste the join command output from the command line into the server.xml file.
  4. Configure the server.xml file to have all information for your Java application.
    (You can download a sample server.xml file and a related social.xml file from GitHub at tam512/restapi4runtimes.)
  5. Repeat the steps 2-4 to join server2 to the Liberty collective and configure the server.
  6. If you want, you can configure the server.xml file so that some APIs are private. In the sample social.xml file, the SocialSphereAllergyForecast API in the SocialSphere application is private. See the following example:
    	<apiDiscovery>
    	           <webModuleDoc contextRoot="/SocialSphereAllergyForecast" public="false"  />
    	     </apiDiscovery>
  7. Restart the Liberty members and then view them in Admin Center at https://controllerHost:httpsPort/adminCenter. Click Explore > Servers to view all servers in the Liberty collective. In the example in this tutorial, two Liberty members are deployed with the SocialSphere application under a Liberty server cluster named SSCluster. The following screen capture shows what the Admin Center looks like: Screen capture of Admin Center servers view of Liberty members
    Screen capture of Admin Center servers view of Liberty members
3

Deploy the Node.js server to the Liberty collective

In this section, you learn how to create sample applications using LoopBack (a Node.js framework) on the Node.js machine. Then you deploy a Node.js server to the Liberty collective.

  1. Create two LoopBack applications: helloworldsample and notes. Deploy the helloworldsample application on a Node.js server. Deploy the notes application with Node.js in Docker, as described in step 4. For more information about creating a Node.js LoopBack application, see The API Connect Developer Toolkit sample code on npm, Inc website.
    1. If the API Connect Developer Toolkit is not already installed on the machine, install it using command npm install -g apiconnect.
    2. Create helloworldsample LoopBack application by running the following command: # apic loopback --name helloworldsample
      Enter helloworldsample for the application name.
      Enter helloworldsample for the directory to contain the project.
      Use arrow keys to select the hello-world application.
    3. Create a sample notes LoopBack application with the following command:
      # apic loopback --name notes
      Enter notes for the application name.
      Enter notes for the directory to contain the project.
      Use arrow keys to select the notes application.
      After creating the two loopback sample applications, you see two folders named helloworldsample and notes in the directory where you run the apic loopback command, as shown in the following screen capture: Screen capture of list of LoopBack applications
      Screen capture of list of LoopBack applications

      In each application folder, you see a package.json file and common, definitions, node_modules, and server directories.

    4. To deploy the Node.js LoopBack application to the Liberty collective, you must package the application in an archive file with a .tgz extention.
      Run the following command in the same directory as helloWorld and notes to create hellworldsample-1.0.0.tgz and notes-1.0.0.tgz files:
      		# wlpn-server pack hellworldsample
      		Finished packing to /opt/hellworldsample-1.0.0.tgz
      		
      		# wlpn-server pack notes	
      		Finished packing to /opt/notes-1.0.0.tgz
  2. On the Admin Center, deploy the Node.js server:
    1. Run registerHost or updateHost by running the wlpn-collective command on the Node.js machine:
      		# wlpn-collective registerHost targetHost  --host=controllerHost --port=controllerHTTPSPort  --user=adminUser --password=adminPassword --rpcUser=osUser --rpcUserPassword=osPassword --autoAcceptCertificates

      The rpcUser must have operating system rights to the target deployment location.

    2. If registerHost is already registered to the Liberty collective, and there is information that needs to be updated such as a new pcUserPassword, then you need to run the updateHost command.
      		# wlpn-collective updateHost targetHost  --host=controllerHost --port=controllerHTTPSPort  --user=adminUser --password=adminPassword --rpcUser=osUser --rpcUserPassword=osPassword --autoAcceptCertificates
    3. Put the hellworldsample-1.0.0.tgz application in a directory on the same machine where you access the Admin Center, for example, C:\nodejsApps.
    4. Add the following information to the controller server.xml file:
      <collectiveController user="adminUser" password="adminPassword" />
      <deployVariable name="wlpn.appPort" value="9091" increment="2"/>
      <deployVariable name="wlpn.adminPort" value="9454" increment="2"/>

      <remoteFileAccess writeDir="c:/nodejsApps"/>

      Configure wlpn.appPort and wlpn.adminPort to avoid duplicate ports when you deploy multiple Node.js servers. The remoteFileAccess parameter contains the location of the Node.js application that is deployed to the collective.

    5. Restart the controller with the –clean option:
      		# wlp/bin/server stop myController --clean
    6. Log in to http://controllerHost:httpsPort/adminCenter with the user ID and password that is defined in the quickStartSecurity section of the controller server.xml file:
    7. In the Toolbox, click Deploy.
    8. On the Deploy page, select Node.js, and then click Next.
    9. Select Application Package, and then click Next.
    10. On the next page, click Confirm.
    11. Browse to the helloworldsample-1.0.0.tgz application from the location that is specified in the remoteFileAccess in the controller server.xml file. The Deployment Parameters for the Application Directory and Server Package File information is filled in automatically. You can manually change the Cluster Name and Server Name fields if needed.
    12. Select the Node.js host that is registered to the Liberty controller.
    13. Enter a Keystore Password to protect the newly generated files.
    14. Click Deploy.

      On the Your deployment is complete screen, click View successfully deployed servers to see the deployed member on a new tab of the browser.

      The following screen capture shows the deployed node.js-server1 server in the WebSphere Liberty collective:

      Screen capture of viewing the                             deployed Node.js server in Admin Center
      Screen capture of viewing the deployed Node.js server in Admin Center
    15. On the Node.js machine, verify that the Node.js server was created after the deployment:
      		# wlpn-server list
      		The following servers are defined relative to the user directory /root/wlpn
      		nodejs-server1
    16. Start the Node.js server using either the wlpn-server command or the WebSphere Liberty Admin Center.
      • Run the following command on the Node.js machine:
        			# wlpn-server start nodejs-server1
      • In the servers view of Admin Center, click the down arrow at the top right of the server and select Start.
    17. Check Node.js member logs by viewing the /root/wlpn/nodejs-server1/log/server.log file on the Node.js machine.
    18. To push the APIs from the Node.js application to the Liberty collective, set the publishSwagger flag to true in the join.json file. After you deploy the Node.js server, the join.json file is created in the /root/wlpn/nodejs-server1 directory. The file should look like the following example:
      		{
      		    "hostName": "aussvt101.rtp.raleigh.ibm.com",
      		    "userDir": "/root/wlpn",
      		    "serverName": "nodejs-server1",
      		    "keystorePassword": "{xor}Lz4sLCgwLTs=",
      		    "controllerList": [
      		        "https://aussvt108.rtp.raleigh.ibm.com:9445"
      		    ],
      		    "clusterName": "nodejs-cluster1",
      		    "appPort": "9091",
      		    "adminPort": "9454",
      		    "publishSwagger" : "true"
      		}
    19. Restart the Node.js server.
4

Create a Node.js server in a Docker image and deploy it to the Liberty collective

This section demonstrates how to create a Node.js server in a Docker image with the the notes loopback application and deploy it to the Liberty collective.

  1. Verify that Docker is installed correctly on the Docker machine:
    		# docker run hello-world

    You should see the following message:

    	Hello from Docker!
    	This message shows that your installation appears to be working correctly.
    	To generate this message, Docker took the following steps:
    	 1. The Docker client contacted the Docker daemon.
    	 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
    	 3. The Docker daemon created a new container from that image which runs the
    	    executable that produces the output you are currently reading.
    	 4. The Docker daemon streamed that output to the Docker client, which sent it
    	    to your terminal.
    	To try something more ambitious, you can run an Ubuntu container with:
    	 $ docker run -it ubuntu bash
    	Share images, automate workflows, and more with a free Docker ID:
    	 https://cloud.docker.com/
    	For more examples and ideas, visit:
    	https://docs.docker.com/engine/userguide/
  2. Run the following command to list Docker images and you should see the hello-world image.
    		# docker images
    		REPOSITORY        TAG                 IMAGE ID            CREATED             SIZE
    		hello-world             latest              48b5124b2768        6 weeks ago         1.84 kB
  3. Download the Node.js v4.7.3 image from https://hub.docker.com/_/node/:
    		# docker pull node:4.7.3
  4. List docker images to make sure node 4.7.3 was download to the docker machine:
    	# docker images
    	REPOSITORY         TAG                 IMAGE ID            CREATED             SIZE
    	node                       4.7.3               66a83b6db17d        2 weeks ago         653 MB
    	hello-world             latest              48b5124b2768        6 weeks ago         1.84 kB
  5. Use the Dockerfile example to build a new Node.js image.
    • Create a directory such as /opt/Nodejs_Docker. Then put the following files in the directory: Dockerfile and the notes-1.0.0.tgz application that you created on the Node.js machine in Step 3. Deploy the Node.js server to the Liberty collective, and the joinMember and removeMember scripts. See Example Dockerfile for a Node.js member image in the WebSphere Liberty documentation.
    • Before you build the Node.js image, list the files in the /opt/Nodejs_Docker directory to make sure all needed files are available:
      		# ls /opt/Nodejs_Docker
      		Dockerfile                            
      		removeMember
      		joinMember
      		notes-1.0.0.tgz
    • In the following sample Dockerfile, you can see that it builds the Node.js image based on the node:4.7.3 image. It adds joinMember and removeMember scripts to the container, installs API Connect, and creates a default server with the notes-1.0.0.tgz application.
      		# Dockerfile to create a Node.js image
      		#
      		# This Dockerfile makes the following assumptions:
      		# - The collectives enabling scripts (joinMember, removeMember) will be placed in
      		#   /opt/ibm/docker in the Docker container
      		# - Node.js servers are created at /root/wlpn
      		# - The Node.js server will be "defaultServer" (for example, /root/wlpn/defaultServer)
      		# - The application to install will already have its dependencies resolved by "npm install"
      		# - The Docker container will be run using --net=host, so that no ports are explicitly exported in this file
      		FROM node:4.7.3
      		#
      		# Auto-start the Node.js server with the container
      		#
      		ENTRYPOINT ["/usr/local/bin/wlpn-server", "run", "defaultServer"]
      		# Add collectives enabling scripts
      		#
      		ADD joinMember /opt/ibm/docker/
      		RUN chmod +x /opt/ibm/docker/joinMember
      		ADD removeMember /opt/ibm/docker/
      		RUN chmod +x /opt/ibm/docker/removeMember
      		#
      		# Update the OS and JRE
      		#
      		RUN apt-get update
      		#
      		# Install APIConnect collective member
      		#
      		RUN npm install -g apiconnect-collective-member
      		#
      		# Use the code below to install an application for use onto the Docker image
      		#
      		COPY notes-1.0.0.tgz /root/wlpn/
      		RUN wlpn-server unpack defaultServer /root/wlpn/notes-1.0.0.tgz
    • Run the build command using the following syntax: docker build -t ${imageName} ${Dockerfile location}. Run the following command in the /opt/Nodejs_Docker directory to create the nodejsapi153 image:
      		# docker build -t nodejsapi153 .

      (The . at the end of the command specifies the location of the Dockerfile.)
    • List images to see the nodejsapi153 image that you created:
      		# docker images
      		REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
      		nodejsapi153         latest              7419eda396a8        2 days ago          1.05 GB
      		node                       4.7.3               66a83b6db17d        2 weeks ago         653 MB
      		hello-world             latest              48b5124b2768        6 weeks ago         1.84 kB
  6. Use the Admin Center to deploy the local nodejsapi153 image on the Docker machine to the Liberty collective.
    • Run registerHost from the controller machine to register the Docker host to the Liberty controller.
      		# wlp/bin/collective registerHost dockerHost --host=controllerHost --port=controllerHTTPSPort --user=adminUser --password=adminPassword --rpcUser=osUser --rpcUserPassword=osUserPassword --autoAcceptCertificates
    • Log in to the Admin Center at http://controllerHost:httpsPort/adminCenter, click Deploy and select the option to deploy the Node.js Server and the Docker Container. Click Confirm.
    • Under Deployment Parameters, type the correct Node.js Docker image name that you built in the Docker machine, which is nodejsapi153 in the previous example. The Cluster Name and Container Name fields are filled in automatically, but you can change them, for example to nodejsdoc_cluster and nodejsdoc_container.
    • Select the Docker host that was registered to the collective, as shown in the following screen capture: Screen capture of selecting the Docker host
      Screen capture of selecting the Docker host
    • Enter a password for the keystore, and click Deploy.
    • View the Admin Center servers, and you see nodejsdoc_container is a member, as shown in the following screen capture: Screen capture of viewing Node.js in Docker container member in Admin Center
      Screen capture of viewing Node.js in Docker container member in Admin Center
  7. From the Admin Center, start the nodejsdoc_container member.
  8. Go to the Docker machine to see the new Node.js Docker container created during deployment:
    	# docker ps -a
    	CONTAINER ID        IMAGE                               COMMAND                  CREATED             STATUS                      PORTS               NAMES
    	7a4a954c6792        nodejsapi153             "/usr/local/bin/wl..."   2 days ago          Up 24 hours                                     nodejsdoc_container
    	13fb833cc324        hello-world                   "/hello"                 57 minutes ago      Exited (0) 57 minutes ago                       wonderful_bose
  9. Similar to what you did for the Node.js member, set the publishSwagger flag to true in the join.json file, which pushes the APIs in the notes LoopBack application to the Liberty collective. The join.json file is created inside the nodejsdoc_container in /root/wlpn/defaultServer when it is joined to the collective.
    • Copy the join.json file from the nodejsdoc_container to the local machine:# docker cp nodejsdoc_container:/root/wlpn/defaultServer/join.json.
    • Edit the join.json file to add "publishSwagger" : "true" to push APIs to the collective, shown in the following example:
      		{
      		    "hostName": "docker103.rtp.raleigh.ibm.com",
      		    "userDir": "Docker",
      		    "serverName": "nodejsdoc_container",
      		    "keystorePassword": "{xor}Lz4sLCgwLTs=",
      		    "controllerList": [
      		        "https://aussvt108.rtp.raleigh.ibm.com:9445"
      		    ],
      		    "clusterName": "nodejsdoc_cluster",
      		    "appPort": "9115",
      		    "adminPort": "9478",
      		    "publishSwagger" : "true"
      		}
    • Copy the join.json file that has the "publishSwagger" : "true" flag back to the nodejsdoc_container.
      			# docker cp join.json nodejsdoc_container:/root/wlpn/defaultServer/
  10. Restart the nodejsdoc_container member from either the Admin Center or with the docker command on the Docker machine.
    		# docker stop nodejsdoc_container
    		# docker start nodejsdoc_container
    • To view docker logs, use the following command:
      		# docker logs <containerName>
    • To tail the end of the log, use the following command:
      		# docker logs --tail=all –f  <containerName>
    • In Red Hat Linux machine, the Docker container logs are in the /var/lib/docker/containers directory. To list all Docker container logs, run the following command:
      		# ls -l /var/lib/docker/containers/*/*-json.log
5

Create a Liberty server in a Docker image and deploy it to the Liberty collective

This section demonstrates how to create a Liberty server in a Docker image with an example Airline Java application and deploy it to the Liberty collective.

Create the Liberty in Docker image on the same machine where you created the Node.js server in a Docker image in Step 4. Create a Node.js server in a Docker image and deploy it to the Liberty collective.

  1. Pull down the beta version of the webSphere-liberty image from the Docker Hub websphere-liberty repository with the following command:
    		# docker pull websphere-liberty:beta
  2. Build a new Liberty in Docker image using Dockerfile:
    • Create a new directory such as /opt/Liberty_Docker, put the following files in the directory: Dockerfile, airlines.war, server.xml, and joinMember and removeMember scripts. See Example Dockerfile for a Liberty Network Deployment image.
    • To make sure all needed files are available before building the Liberty Docker image, list files in the /opt/Liberty_Docker directory:
      		# ls /opt/Liberty_Docker
      		airlines.war
      		Dockerfile
      		joinMember
      		removeMember
      		server.xml
    • In the following sample Dockerfile, the file builds the Liberty image from websphere-liberty:beta image. It adds joinMember and removeMember scripts to the container, installs the needed Liberty features, adds Liberty server.xml to the defaultServer in the container, and add the airlines.war to the dropins directory.
      			# Dockerfile to create a Liberty Network Deployment image
      			#
      			# This Dockerfile assumes:
      			# - The collective enabling scripts (joinMember, removeMember) will be placed in
      			#   /opt/ibm/docker in the Docker container
      			# - WebSphere Liberty will be installed at /opt/ibm/wlp
      			# - The WebSphere Liberty server will be "defaultServer"
      			#   (for example, /opt/ibm/wlp/usr/servers/defaultServer)
      			# - The Docker container runs using --net=host so that no ports are explicitly
      			#   exported in this file
      			
      			FROM websphere-liberty:beta
      			
      			#
      			# Auto-start the Liberty server with the container
      			#
      			ENTRYPOINT ["/opt/ibm/wlp/bin/server", "run", "defaultServer", "--clean"]
      			#
      			# Add collective enabling scripts
      			#
      			ADD joinMember /opt/ibm/docker/
      			RUN chmod +x /opt/ibm/docker/joinMember
      			ADD removeMember /opt/ibm/docker/
      			RUN chmod +x /opt/ibm/docker/removeMember
      			#
      			# Update the operating system
      			#
      			RUN apt-get update
      			#
      			# Add the additional required features
      			#
      			RUN installUtility install --acceptLicense scalingMember-1.0 clusterMember-1.0 collectiveMember-1.0 apiDiscovery-1.0
      			ADD server.xml /opt/ibm/wlp/usr/servers/defaultServer/
      			#
      			# Insert your application file name. This statement copies the application
      			# onto the Docker image.
      			#
      			ADD airlines.war /opt/ibm/wlp/usr/servers/defaultServer/dropins/
    • The the following example of a Liberty server.xml file that has features needed for the example Airlines application. The httpPort and httpsPort in this server.xml file have variables ${memberHttpPort} and ${memberHttpsPort}. The variables are defined in the controller server.xml file to avoid conflict ports when you deploy multiple Liberty servers in Docker containers.
      		<server description="server1">
      		    <!-- Enable features -->
      		        <featureManager>
      		                <feature>localConnector-1.0</feature>
      		                <feature>apiDiscovery-1.0</feature>
      		                <feature>jsp-2.3</feature>
      		                <feature>jsonp-1.0</feature>
      		                <feature>jaxrs-2.0</feature>
      		        </featureManager>
      		
      		        <httpEndpoint id="defaultHttpEndpoint"
      		                 host="*"
      		                 httpPort="${memberHttpPort}"
      		                 httpsPort="${memberHttpsPort}" />
      		
      		        <basicRegistry id="basic">
      		                <user name="admin" password="password"/>
      		                <user name="nonadmin" password="password"/>
      		        </basicRegistry>
      		
      		        <applicationMonitor updateTrigger="mbean"/>
      		</server>
    • Build a libertybeta-docker image by running the following command in the /opt/Liberty_Docker directory: # docker build -t libertybeta-docker .(The . at the end of the command specifies the location of the Dockerfile.)
    • List docker images to see the new libertybeta-docker image:
      		# docker images
      		REPOSITORY              TAG           IMAGE ID            CREATED             SIZE
      		libertybeta-docker   latest         4d932b4c51b3        40 seconds ago      454 MB
      		websphere-liberty       beta            0e90e2108d31        44 hours ago        402 MB
      		nodejsapi153          latest              7419eda396a8        2 days ago          1.05 GB
      		node                      4.7.3               66a83b6db17d        2 weeks ago         653 MB
      		hello-world             latest              48b5124b2768        6 weeks ago         1.84 kB
  3. Use the Admin Center to deploy the local libertybeta-docker image that is on Docker machine to the Liberty collective. If you want to deploy a Docker image that is in Docker hub registry, see Step 6. Deploy a Docker image in a Docker Hub Registry to the Liberty collective.
    • If you use the same Docker machine for the Node.js server in a Docker container, you do not need to run registerHost again. If you use a new machine, you need to run registerHost from the controller machine to register the new machine to the collective before you deploy.
    • Add the following information to the controller server.xml file and then restart the controller.
      		<collectiveController user="adminUser" password="adminPassword"/>
      	     <deployVariable name="memberHttpPort" value="9090" increment="2"/>
               <deployVariable name="memberHttpsPort" value="9453" increment="2"/>

      If collectiveController is already configured in the controller server.xml file, do not add it again. The memberHttpPort and memberHttpsPort values are defined to avoid conflict ports as previously described.

    • Log in to the Admin Center at http://controllerHost:httpsPort/adminCenter and select Deploy. Select to deploy Liberty Server and Docker Container and click Confirm.
    • Enter the correct Liberty Docker image name, libertybeta-docker, that you built in the previous example. The Cluster Name and Container Name are filled out automatically, but you can change them, for example libertybeta-docker_cluster and libertybeta-docker_container, as shown in the following screen capture: Screen capture of WebSphere Liberty in Docker deployment parameters
      Screen capture of WebSphere Liberty in Docker deployment parameters
    • Scroll down and select the registered docker host, as shown in the following screen capture:Screen capture of selecting a registered Docker host
      Screen capture of selecting a registered Docker host
    • Enter a password for the keystore and click Deploy. Then use the Admin Center to view the deployed Liberty server in a Docker container, as shown in the following screen capture:Screen capture of viewing Liberty in a Docker container member in                     the Admin Center
      Screen capture of viewing Liberty in a Docker container member in the Admin Center
6

Deploy a Docker image in a Docker Hub Registry to the Liberty collective

In this section you get a root certificate from a Docker Hub, you push a local Docker image to Docker Hub registry, and you deploy the image from the registry to the Liberty collective. This section uses the libertybeta-docker image that you created in Step 5. You create a Liberty server in a Docker image and deploy it to the Liberty collective.

To deploy a Docker image from a registry, you must configure the Liberty controller to have access to the registry.

  1. Import the root certificate to the Liberty collective keystore:
    1. Export the GeoTrust Global CA root certificate from https://hub.docker.com/
      For example, in a Firefox browser, complete the following steps:
      • Click the lock symbol next to the URL, select hub.docker.com > More information > View Certificate > Details > GeoTrust Global CA > Export (to DER file).
      • Click the lock icon, as shown in the following screen capture:Screen capture of Lock icon on Docker Hub
      • Click the right arrow next to hub.docker.com and then click More Information.
      • Under Website Identity, click View Certificate.
      • In the Certificate Viewer, click Details.
      • Under Certificate Hierarchy, select GeoTrust Global CA and then click Export.
      • Save the certificate file as GeoTrustGlobalCA.der.
    2. Stop the controller if it is running.
    3. Copy the GeoTrustGlobalCA.der certificate file to the controller machine.
    4. Import the certificate into the collective keystore using the following keytool command and respond yes to trust this certificate.
      	# keytool -import -file certFile -keystore path_to_controller_collectiveTrust.jks -storepass controller_keystore_password -alias any_unique_value

      For Example: # /Liberty/java/bin/keytool -import -file /tmp/GeoTrustGlobalCA.der -keystore /Liberty/wlp/usr/servers/myController/resources/collective/collectiveTrust.jks -storepass controllerkspasswd -alias dockerhub

      	CertOwner: CN=GeoTrust Global CA, O=GeoTrust Inc., C=US
      	Issuer: CN=GeoTrust Global CA, O=GeoTrust Inc., C=US
      	…………………….....
      	………………………..
      	Trust this certificate? [no]:  yes
      	Certificate was added to keystore
    5. Push the libertybeta-docker local Docker image that you created in Step 5 to the Docker hub registry.
      1. Make sure that you have a Docker Hub account. Create a Docker ID from the Docker website.
      2. Find the local libertybeta-docker image ID:
        	# docker images
        	REPOSITORY        TAG        IMAGE ID       CREATED        SIZE
        	libertybeta-docker    latest      4d932b4c51b3     2 hours ago      454 MB
    6. Tag the libertybeta-docker image ID as shown in the following command example:

      # docker tag 4d932b4c51b3 tamdocker/libertybeta-docker:demo, where tamdocker is your Docker Hub account name and demo is a tag name.

    7. List the Docker images to view the tagged image:
      	# docker images
      	REPOSITORY      TAG          IMAGE ID       CREATED        SIZE
      	libertybeta-docker    latest        4d932b4c51b3     2 hours ago      454 MB
      	tamdocker/libertybeta-docker  demo  4d932b4c51b3     2 hours ago      454 MB
    8. Log in to your Docker account:
      	# docker login
      	Login with your Docker ID to push and pull images from Docker Hub. If you don't have a Docker ID, head over to https://hub.docker.com to create one.
      	Username: tamdocker
      	Password: xxxxxxxx
      	Login Succeeded
    9. Push the tagged image to the Docker Hub:
      	# docker push tamdocker/libertybeta-docker:demo
      	The push refers to a repository [docker.io/tamdocker/libertybeta-docker]
      	77a69c4adc38: Pushed
      	……….……………
      	demo: digest: sha256:472209032316b233e8ad8034593fd5b6a64abf57815788fac390e5ca9ca33eb1 size: 4082
    10. Verify that the image was pushed to Docker Hub by viewing your registry in Docker Hub, which should look like the following screen capture:Screen capture of viewing a Docker image on Docker Hub
      Screen capture of viewing a Docker image on Docker Hub
  2. Configure the Liberty Controller to have access to the docker registry.
  3. Put the following information in the controller server.xml file. Change the values to match with your docker information:
    		<!-- Docker registry connection information -->
    		<variable name="dockerRegistryTokenURL" value="https://auth.docker.io/token?service=registry.docker.io" />
    		<variable name="dockerRegistry" value="https://registry.hub.docker.com/v2" />
    		<variable name="dockerRepository" value=" tamdocker/libertybeta-docker" />
    		<variable name="dockerUser" value="tamdocker" />
    		<variable name="dockerUserPassword" value="xxxxxxx" />
    		<variable name="dockerUserEmail" value="tamdinh@us.ibm.com" />
  4. Restart the controller with --clean option.
  5. Deploy tamdocker/libertybeta-docker:demo from registry to the Liberty collective.
    1. Follow the same steps to deploy a Liberty in Docker container using Admin Center. At the Deployment Parameters, you see a demo tag for the tamdocker/libertybeta-docker image .
    2. Select demo and it automatically fills in Image Name, Cluster Name, and Container Name fields as shown in the following screen capture: Screen capture of deploying parameters for a Docker image in a registry
      Screen capture of deploying parameters for a Docker image in a registry
    3. Finish deploying this image as described in previous sections. Then view the deployed image in the Admin Center as shown in the following screen capture: Screen capture of viewing a demo_container docker image in Admin Center
      Screen capture of viewing a demo_container docker image in Admin Center
7

Expose all APIs in the applications in a Liberty collective

Now there are six members in the Liberty collective as shown in the previous screen capture. Ensure that all members are running, so you can expose all APIs in the applications on these members through the WebSphere Liberty collective explorer. If one application is installed on multiple members, the APIs of the application are shown only once. In the tutorial, the SocialSphere application is installed on two Liberty members, and the Airline application is installed on the demo-container and libertybeta-docker_container members.

  1. View public APIs in the collective:
    • If <apiDiscovery publicURL="myPublicAPI" …/> is configured in the controller server.xml file, then the public API URL is http://controlerHost:httpPort/myPublicAPI/collective/explorer.
    • If the publicURL is not configured, then the default public API URL is http://controlerHost:httpPort/api/collective/explorer.
    • In a browser, type http://controlerHost:httpPort/myPublicAPI/collective/explorer. In the following screen capture of all public APIs, the SVT logo on blue background banner is the customized banner. (The default banner is IBM logo on a black background.) Screen capture of exposing public                     APIs
      Screen capture of exposing public APIs

    The Liberty REST APIs with Custom Banner title and the List of available API description are the customized information as defined in the swaggerDef.yaml file in Step 1. Configure a Liberty collective. It displays a list of all available public APIs.

    • The APIs in Airlines application are displayed as Airline Booking API, as shown in the following screen capture:Screen capture of Airlines                     application APIs
      Screen capture of Airlines application APIs
    • The APIs in the SocialSphere application are default, Weather API and AllergyForecast, but the AllergyForecast is not shown since it is configured as a private API. The APIs in this application are shown once, even though it was installed on two Liberty members. The following two screen captures show the Defaul API and the Weather API in the SocialSphere application: Screen capture of the default API in SocialSphere                             application
      Screen capture of the default API in SocialSphere application
      Screen capture of the Weather API in SocialSphere                             application
      Screen capture of the Weather API in SocialSphere application
    • The APIs in the hello-world LoopBack application as shown in the following screen capture:Screen capture of LoopBack hello-world application APIs
      Screen capture of LoopBack hello-world application APIs
    • The APIs in the notes LoopBack application as shown in the following screen capture: Screen capture of Loopback notes application APIs
      Screen capture of Loopback notes application APIs
  2. View all APIs (both public and private) in the collective:
    • In a browser, type https://controllerHost:httpsPort/ibm/api/collective/explorer.
    • Log in with the quickStartSecurity user name and password.
      You see all APIs listed, as shown in the following screen capture: Screen capture of the Liberty REST APIs with                                     Custom Banner
      Screen capture of the Liberty REST APIs with Custom Banner
    • View the private AllergyForecast API in the SocialSphere application, as shown in the following screen capture: Screen capture of the AllergyForecast API in the SocialSphere application
      Screen capture of the AllergyForecast API in the SocialSphere application

Conclusion

In this tutorial, you learned how to deploy four runtime environments to a WebSphere Liberty collective: Java, Node.js, Nodejs in Docker, and Liberty in Docker.

You also learned to deploy a Docker image on a local machine and how to deploy a Docker image from the Docker Hub registry.

Finally, you saw how to use WebSphere Liberty to expose all of the APIs in the applications from four runtime environments.

Now you know how to make APIs from a WebSphere Liberty collective available all in one place, where you and other developers can view and invoke all of your application APIs. Try it in your own environment, and use the power of the API Discovery 1.0 feature in WebSphere Liberty.

Acknowlegements

The author would like to thank Arthur De Magalhaes for all of his technical support and reviews and Mei-hsiang Chang for reviews and very helpful comments.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Middleware
ArticleID=1045286
ArticleTitle=Expose APIs in a WebSphere Liberty collective
publish-date=04302017