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.
- Run the existing application using the IBM Cloud Private catalog.
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 banking APIs. It makes banking services reachable through APIs 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. This will be referenced later as "YOUR_USERNAME"
- Enter an email.
- Create a password.
- Click Sign up for GitHub.
- Select the plan Unlimited public repositories for free.
- A Confirmation email will be sent. Verify your email address to collaborate in Github.
-
Fork the banking application from this GitHub repository to your own GitHub repository.
- Click Fork.
- Github automatically forks this project from this repository IBM/ICp-banking-microservices to your repository YOUR_USERNAME/ICp-banking-microservices.
- Discover your forked project (your fresh banking application) in your Github repository YOUR_USERNAME/ICp-banking-microservices.
-
Install the Git command line interface to manage your GitHub repository. Git has three main commands:
- git clone is the command for creating a local copy of the source code from a GitHub repository.
- git pull is the command for pulling fresh code from a GitHub repository.
- git push is the command for pushing new code to a GitHub repository.
-
Launch a terminal and clone your GitHub repository ICp-banking-microservices to create a local copy of your banking application:
git clone https://github.com/YOUR_USERNAME/ICp-banking-microservices
-
Import the source code into your favorite IDE and take a look at the banking-application folder:
- app.js: the application server code.
- public/index.html: the application client code (banking dashboard).
- public/css: the application stylesheet.
- public/js: the 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 dependencies file.
- Dockerfile: file to build the docker image. it will be used later (step 2).
-
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 and test if Node.Js and npm are installed in your operating system and added to the system path:
- Run the command node -v. The version is displayed.
- Run the command npm -v. The version is displayed.
-
In the same terminal. Go to your banking application folder:
cd ICp-banking-microservices/banking-application -
Install Node.Js package dependencies of the banking application using :
npm install package.json
- As a result, dependencies are installed in your project folder.
-
Run the banking application using :
node banking-application/app.js:
- As a result, The banking application is started.
-
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 ICp-banking-microservices:
git push" -
Go back to your online Github repository ICp-banking-microservices using the web browser.
- Check that your code has been updated with commit label Update of BankingAPI.js
👍 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.
In this Code Pattern, An automatic deployment process has been set up in the ICp Worker Node on Linux on Z. First, it automatically builds a Docker image from a GitHub repository with a DevOps approach. Then, it deploys the Docker image to the Docker repository of the ICp Worker Node based on Linux on Z.
-
Copy and Paste this URL into your browser address bar and replace GITHUB_USERNAME with your username :
http://148.100.93.200:20002/deploy/GITHUB_USERNAME
-
Click Enter. The deployment is processing :
- The process pulls your source code from your GitHub repository YOUR_USERNAME/ICp-banking-microservices.
- The process builds the Docker image from the Docker file described before.
- The build action automatically adds the Docker image to the Docker image repository of the ICp Worker Node on Linux on Z.
- The Docker image is YOUR_USERNAME-icp-banking-microservices. It is tagged lastest. This is your docker image name and will be refered as "YOUR_IMAGE_NAME".
-
Wait for the successful completion of your build:
-
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.
-
Subscribe to the IBM Cloud Private hosted in the Linux One Community Cloud
- Click Try Container
- Fill the form and register to ICP
-
Login to the IBM Cloud private catalog and fill credentials with yours:
- Replace the username:
**** - Replace the password:
****
- Replace the username:
-
Click the top-right icon from the menu to access the catalog.
- Click on Catalog
-
Click on the Helm Chart called openmplbank - Banking dashboard 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 YOUR_USERNAME (limit of 30 characters).
- Select the default namespace to codepatterns.
- Fill Image repository with your Docker image name, YOUR_IMAGE_NAME.
-
Click the Install button. When the process is finished, click View Helm Release
-
From the Helm release view, the container details are displayed.
- Click on Launch to display the banking microservice.
-
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.
-
From the Helm Release view, Delete your banking microservice after use.
- Click on Action then Delete.
👍 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.