In this Code Pattern, you will build and deploy a banking microservice with IBM Cloud private running in the LinuxONE Community Cloud.
IBM Cloud Private is a private cloud platform for developing and running workloads locally. It is an integrated environment that enables you to design, develop, deploy and manage on-premises, containerized cloud applications behind a firewall. It includes the container orchestrator Kubernetes, a private image repository, a management console and monitoring frameworks.
When you will complete this Code Pattern, you will understand how to:
- Build a Docker image from an existing application.
- Deploy a Docker image to IBM Cloud Private.
- Deploy a Helm chart.
- Use the catalog from IBM Cloud Private.
This journey accesses a fictitious retail banking system called MPLbank. MPLbank integrates an Account Management System running on IBM Mainframe. On top of this component, an API layer based on IBM API Connect has been set up to deliver a banking API. It makes banking services reachable through API from all kind of applications. IBM Cloud private has been configured into the LinuxOne LinuxONE Community Cloud.
- The user deploys the application based microservice on the Worker Node on Linux on Z using IBM Cloud Private.
- The user installs and runs an instance of his microservice from IBM Cloud Private. The application calls a banking API published in API Connect.
- API Connect calls the back-end Z Mainframe through a banking API published in z/OS Connect EE.
- z/OS Connect EE calls the Account Management System (AMS) running in CICS. A COBOL program processes the request and returns banking data. Finally, banking data are sent back to microservice application in the Worker Node on Linux on Z.
- IBM Cloud private
- IBM API Connect
- IBM z/OS Connect Enterprise Edition
- IBM CICS Tansaction Server
- IBM Db2
- Part 1 - Discover the banking application
- Part 2 - Subscribe to the banking API through the API Developer Portal
- Part 3 - Run the banking application with Node.js
- Part 4 - Push the banking application to your GitHub repository
- Part 1 - Discover the Helm chart from the calalog
- Part 2 - Configure and install your banking microservice
- Part 3 - Access your banking microservice
The objective is to discover the banking application located in the banking-application folder. This application is a Node.js application. It will be locally tested before packaging it into a Docker image for IBM Cloud private.
-
Create a GitHub account.
- Pick a username.
- Enter an email.
- Create a password.
- Click Sign up for GitHub.
-
Fork the banking application from this GitHub repository to your own GitHub repository.
- Click Fork.
-
Install the Git command line interface to manage your GitHub repository.
- Use git clone command to create a local copy of the source code from a GitHub repository.
- Use git pull command to get fresh code from your GitHub repository.
- Use git push command to push new code to your GitHub repository.
-
Launch a terminal and clone your GitHub repository to create a local copy of your banking application:
git clone https://github.com/YOUR_USERNAME/YOUR_REPOSITORY_NAME
-
Import the source code into your favorite IDE and take a look at the banking-application folder:
- app.js: the Node.js application (server code).
- public/index.html: the banking application (client code).
- public/css: the banking application stylesheet.
- public/js: Javascript libraries. bankingAPI.js will be modified later to connect the banking application to a real corebanking system through API calls (part 2).
- package.json: the package dependency file.
- Dockerfile: file to build the docker file. it will be used later.
-
Sign up for an IBM ID if you don't have one already.
-
Go to the API Developer Portal.
-
Create an account if you have not done that already.
- Click Create an Account.
- Provide all required information. Be sure to use your IBM ID (email address) for this account.
- Click Submit.
An account activation email will be sent to your registered IBM ID email. Click on the link in this email to activate your account.
-
Login to your account.
-
Create a new application.
- Click Apps from the menu.
- Click Create new App.
- Fill in all the required fields.
- Click Submit.
Make a note of the client ID and client Secret. You will need them to access the API later.
-
Before working with the banking API, you need to subscribe to it first. Display the list of available API products.
- Click API Products from the top menu.
- Click Banking Product in the list.
-
Subscribe to the Banking API.
- Click Subscribe to the Default Plan.
- Select the App that you have just created before.
- Click Subscribe.
-
Modify the banking-application/js/bankingAPI.js in your banking application.
- Replace YOUR_CLIENT_ID_HERE by your client ID value from the IBM API developer portal.
- Replace YOUR_CLIENT_SECRET_HERE by your client Secret value from the IBM API developer portal.
-
Install these required components for your environment (Windows, Mac OS, Linux):
-
Launch a terminal. Go to your repository root folder:
cd YOUR_REPOSITORY_NAME- From the app root folder, launch the app:
node banking-application/app.js -
Launch a web browser and go to localhost:3000. The banking application appears.
-
Test your application.
- Select a customer ID.
- Please wait while the application calls banking data from the Mainframe through API Connect and z/OS Connect EE.
- The result is displayed in a JSON structure.
-
The banking application locally works. Stop the Node.js server with a SIGINT (CTRL+C) from the terminal.
-
Commit the fresh code you modified to add changes to the local repository:
git commit -m "Update of bankingAPI.js" -
Push the code you commited to transfer the last commit to your GitHub repository:
git push"
👍 Congratulations! Your banking application locally works and modifications have been pushed to your GitHub repository! Ready for IBM Cloud private?
The objective is to build a docker image from the banking application and then deploy it to the IBM Cloud private.
Docker can build images automatically by reading the instructions from a Dockerfile. A Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. Using docker build, users can create an automated build that executes several command-line instructions, step by step.
-
Take a look at the banking-application/Dockerfile:
- FROM ibmcom/ibmnode: This command gathers, from IBM's public Docker repository, a Ubuntu Linux image containing all the basic components to run a Node.js application. It will be used as a basis for our usecase.
- WORKDIR "/app": This command creates a directory inside our image, from which we will inject our specific files.
- COPY package.json /app/: This command copies our package.json file into the working directory inside our image. This file holds information about the app, most importantly the package dependencies it will need.
- RUN cd /app; npm install; npm prune --production: These commands first move our focus to the working directory, then download and install our app's required dependencies.
- COPY . /app: This command copies everything left of the app into our working directory inside the docker image, i.e. our app's source code.
- ENV NODE_ENV production and ENV PORT 3000: These two commands set environment variables. The first one tells our Node.js instance that we run in production mode, and thus don't need development libraries. The other one sets the port 3000 as our main networking port.
- EXPOSE 3000: This command tells docker to map the image's port 3000 to the operating system's port 3000. It will gives us a network access to the docker image and thus the Node.js app.
- CMD ["npm", "start"]: This last command tells Docker what to do when we launch the image, in our case npm start, which will start the Node.js app.
Jenkins is an open source automation server. It helps automate the non-human part of the software development process with continuous integration, and facilitates technical aspects of continuous delivery. It supports version control tools, including Git, and can execute shell scripts. In this Code Pattern, Jenkins has been setup in the ICp Worker Node on Linux on Z. It is used to automatically build a docker image from a GitHub repository to comply with a DevOps approach. After the build process, Jenkins deploys the Docker image to the Docker repository of ICp Worker Node based on Linux on Z.
-
Connect to Jenkins.
-
Select values before building the Docker image:
- Replace GITHUB_USERNAME by your own GitHub username.
- Replace GITHUB_REPOSITORY_NAME by your own GitHub repository name
-
Click Build.
- A new build has been submitted into Jenkins and is in progress.
-
Wait for the successful completion of your build:
-
Select your build then click Console Ouptut and View As plain text to display the build output
-
Read the build output to understand how the Jenkins build has been executed:
- Jenkins pulled your source code from yout GitHub repository.
- Jenkins built the Docker image from the Docker file described before.
- The Docker build action automatically added it to the Docker image repository of the ICp worker node on Linux on Z. Your banking application is now ready to be instantiated from the ICp catalog.
👍 Congratulations! Your banking application has been packaged into a Docker image using a DevOps approach! Ready to use it from IBM Cloud private?
The objective is to discover the IBM Cloud private catalog in order to instantiate a container from your Docker image containing your banking application. In this way, you will be able to test your banking application from ICp.
-
Login to the [IBM Cloud private catalog] () and fill credentials:
- Replace the username:
**** - Replace the password:
****
- Replace the username:
-
Click the top-left icon then go to the catalog from the menu.
- Click on Catalog then Helm Charts.
-
Display customized Helm Charts, including a published helm chart for the banking application
- Click on Filter
- Check local-charts to display customized charts.
-
Click on the Helm Chart called Banking Application to see the overview of the this banking microservice.
-
Select your banking microservice to prepare your container.
- Click Configure.
-
Configure the banking microservice to instantiate a container from your Docker image built in the previous step:
- Fill the release name with GITHUB_USERNAME-GITHUB_REPOSITORY_NAME.
- Set the default namespace to default.
- Fill Image repository to your Docker image called GITHUB_USERNAME-GITHUB_REPOSITORY_NAME.
-
Click the Install button. When the process is finished, click View Helm Release
-
Click on the only deployment available
-
Select access http under the Expose details panel and enjoy your new app!
-
Test your application:
- Select a customer ID.
- Please wait during the application calls banking data from the Mainframe through API Connect and z/OS Connect EE.
- The result is displayed in a JSON structure.
👍 Congratulations! Your banking application has been instantiated from IBM Cloud Private as container. Your banking application succeeded to call banking APIs to call the Mainframe for banking business services.