In this code pattern, we will build a dummy digital bank composed of a set of microservices that communicate with each other. We'll be using Node.js, Express, MongoDB, and the IBM Cloud Container Service.
Development of cloud native apps that are broken down into a set of microservices has been praised and commended as best-practice in software development methodologies. Software stacks like Kubernetes, which enable cloud native computing, have therefore picked up quite a bit of popularity.
It’s a little (a lot) more fun, however, to build a so-called cloud native app, than to talk about one.
So here's our attempt:
We’ll take a use-case that has a bit of real-world familiarity to it — A digital bank. Naturally inspired by Monzo. Let’s call it Innovate.
A live version deployed on a Kubernetes cluster in IBM Cloud is available for you to try here. To test it out, sign up for an account. A process runs periodically to dump randomized transactions and bills for user accounts, so give it a couple of minutes and refresh to see your populated profile.
When you've completed this Code Pattern, you will understand how to:
- Break an application down to a set of microservices
- Create and manage a Kubernetes cluster on IBM Cloud
- Deploy to a Kubernetes cluster on IBM Cloud
- Deploy to IBM Cloud Private
When thinking of business capabilities, our imaginary bank will need the following set of microservices:
- Portal: Loads the UI and takes care of user sessions and relies on all other microservices for core functionality.
- Authentication: Handles user profile creation, as well as login & logout.
- Accounts: Handles creation, management, and retrieval of a user’s banking accounts.
- Transactions: Handles creation and retrieval of transactions made against users' bank accounts.
- Bills: Handles creation, payment, and retrieval of bills.
- Support: Handles communication with Watson Assistant to enable a support chat feature.
- IBM Cloud Kubernetes Service: IBM Cloud Kubernetes Service manages highly available apps inside Docker containers and Kubernetes clusters on the IBM Cloud.
- Microservice Builder: Learn, build, run, and manage applications in a microservices framework.
- Watson Assistant: Create a chatbot with a program that conducts a conversation via auditory or textual methods.
- Microservices: Collection of fine-grained, loosely coupled services using a lightweight protocol to provide building blocks in modern application composition in the cloud.
- Node.js: An open-source JavaScript run-time environment for executing server-side JavaScript code.
- Containers: Virtual software objects that include all the elements that an app needs to run.
- Databases: Repository for storing and managing collections of data.
- Hybrid Cloud: Enabling customers to draw on the capabilities of public cloud service providers while using private cloud deployment for sensitive applications and data.
You have multiple options to setup your own instance:
Clone the innovate-digital-bank repository locally. In a terminal, run:
$ git clone https://github.com/IBM/innovate-digital-bank.gitThis code pattern depends on MongoDB as a session and data store. From the IBM Cloud catalog, find Compose for MongoDB and click create. Give it a name, choose a region, pick the standard pricing plan and click create.
Get your mongo connection string. Almost all your microservices need it; keep it safe!
Each of the 7 microservices must have a .env file that stores all credentials.
An example is already provided within each folder. From the directory of each microservice, copy the example file, rename it to .env, and fill it with the appropriate values.
For example, from within the /innovate folder, navigate into the accounts folder
$ cd accountsNext, copy and rename the .env.example folder
$ cp .env.example .envFinally, edit your .env folder and add your Mongodb connection string
Repeat these steps for all microservices. In addition to your mongo URL, most will need the public IP address of your Kubernetes cluster, You can find that under the overview of your cluster on IBM Cloud.
When running the app locally without Kubernetes, the microservices do not run on the NodePorts specified in our helm chart, so we need to point our portal and userbase microservices to the correct ports.
If you're running on macOS or any linux-based system, run the following in a terminal from the git repo's directory
$ export NODE_ENV=developmentif you're running on Windows, edit the NODE_ENV attribute in your .env file from within the /portal folder and the /userbase folder to the following:
NODE_ENV=developmentFinally, navigate to each microservice folder, and start it. Make sure you run the 7 microservice in 7 separate terminals.
$ npm startYou can now visit localhost:3100 to access the portal
NOTE: This guide requires a paid/upgraded account on IBM Cloud. You cannot complete the steps with a free or lite account.
- Get the tools
- Clone the repo
- Login to IBM Cloud
- Create a cluster
- Create an instance of MongoDB
- Configure your deploy target
- Configure your environment variables
- Configure kubectl
- Initialize helm
- Deploy
You'll need each of the following pre-requisites:
-
The Kubernetes CLI
-
Thee IBM Cloud plugins:
container-service,container-registry, anddev
$ ibmcloud plugin install container-service
$ ibmcloud plugin install container-registry
$ ibmcloud plugin install devClone the innovate-digital-bank repository locally. In a terminal, run:
$ git clone https://github.com/IBM/innovate-digital-bank.gitWe'll need to log into IBM Cloud through both the console and the terminal.
NOTE: If you need to specify the region you want to deploy in, you can do so by adding the
-aflag followed by the region URL.
$ ibmcloud loginFrom the catalog, find Containers in Kubernetes Clusters and click create. Choose a region and a cluster type, and create your cluster. Allow it some time to deploy.
This demo depends on MongoDB as a session and data store. From the catalog, find Compose for MongoDB and click create. Give it a name, choose a region, pick the standard pricing plan and click create.
Get your mongo connection string. Almost all your microservices need it; keep it safe!
Each of the 7 docker images needs to be pushed to your docker image registry on IBM Cloud. You need to set the correct deploy target. Depending on the region you've created your cluster in, your URL will be in the following format
registry.<REGION_ABBREVIATION>.bluemix.net/<YOUR_NAMESPACE>/<YOUR_IMAGE_NAME>
For example, to deploy the accounts microservice to my docker image registry in the US-South region, my deploy_target will be:
registry.ng.bluemix.net/amalamine/innovate-accounts
If you need to get your namespace, run:
$ ibmcloud cr namespace-listYou can also add a new namespace by running:
$ ibmcloud cr namespace-add <NAME>From the directory of each microservice, replace the deploy target in cli-config.yml and in /chart/innovate-<MICROSERVICE_NAME>/values.yaml with the correct one
For example, from within the /innovate folder, navigate into the accounts folder
$ cd accountsNext, edit line 58 of cli-config.yaml file. Replace the deploy-image-target with the correct value.
deploy-image-target: "registry.ng.bluemix.net/amalamine/innovate-accounts"
Edit line 6 of the values.yaml file. Replace the repository with the correct value.
repository: registry.ng.bluemix.net/amalamine/innovate-accounts
Repeat these steps for all 7 microservices.
Each of the 7 microservices must have a .env file that stores all credentials. An example is already provided within each folder. From the directory of each microservice, copy the example file, rename it to .env, and fill it with the appropriate values.
For example, from within the /innovate folder, navigate into the accounts folder
$ cd accountsNext, copy and rename the .env.example folder
$ cp .env.example .envFinally, edit your .env folder and add your Mongodb connection string
Repeat these steps for all microservices. In addition to your mongo URL, most will need the public IP address of your Kubernetes cluster, You can find that under the overview of your cluster on IBM Cloud.
Run the following command:
$ ibmcloud cs cluster-config <YOUR_CLUSTER_NAME>Then copy the output and paste it in your terminal
If you dont have helm installed, see the Helm Documentation.
$ helm initFinally, navigate to each microservice folder, and run the following command
$ ibmcloud dev deployOnce done, you'll be able to access the portal on port 30060 of your cluster's public IP address, which you can find under the overview of your cluster on IBM Cloud.
Or if you are logged in ibmcloud cli, you can find your public ip of your worker node by
$ ibmcloud cs workers <name-of-cluster>If you have an instance of IBM Cloud Private running, you can follow the steps below to deploy the app. If you'd like to deploy your own instance of ICP, you can follow this great writeup.
- Create a persistent volume
- Create a persistent volume claim
- Create an instance of MongoDB
- Configure your environment variables
- Add your ICP's address to your hosts file
- Login to docker
- Configure kubectl
- Configure cloudctl
- Install Helm
- Deploy
This code pattern depends on MongoDB as a session and data store. From ICP's menu, click on Storage > Create persistent volume. Give it a name and a capacity, choose storage type Hostpath, and add a path parameter
From ICP's menu, click on Storage > Create Persistent Volume Claim. Give it a name and a storage request value.
From the catalog, choose MongoDB. Give it a Name, specify the Existing Volume Claim Name, and give it a password.
Get your mongo connection string; Almost all your microservices need it; keep it safe!
Your connection string will be in the following format:
mongodb://<USERNAME>:<PASSWORD>@<HOST>:<PORT>/<DATABASE_NAME>
Each of the 7 microservices must have a .env file. An example is already provided within each folder. From the directory of each microservice, copy the example file, rename it to .env, and fill it with the appropriate values.
For example, from within the /innovate folder, navigate into the accounts folder
$ cd accountsNext, copy and rename the .env.example folder
$ cp .env.example .envFinally, edit your .env folder and add your Mongodb connection string
Repeat those steps for all microservices. In addition to your mongo url, you may the IP address of your ICP.
Add an entry to your /etc/hosts file as follows
<YOUR_ICP_IP_ADDRESS> mycluster.icpFor Mac users, if you are running ICP locally in VM you would also have to add the cluster info to the insecure registry. To do so, go to the Docker icon in the system tray, select Preferences > Daemon, and choose to enable experimental features and add cluster to insecure registries list.
$ docker login mycluster.icp:8500From your ICP's dashboard, copy the kubectl commands under ***REMOVED*** > configure client
IBM Cloud Private provides a custom CLI, similar to kubectl, called cloudctl. To find the CLI for your ICP version, navigate to Menu > Command Line Tools > Cloud Private CLI and follow instruction to get cloudctl installed.
Once you have cloudctl cli installed, log into ICP
$ cloudctl login -a https://mycluster.icp:8443 -u ***REMOVED*** --skip-ssl-validationNOTE: The default password for the local ICP VM is REMOVED.
If you dont have helm installed, see the Helm Documentation.
$ helm initFinally, navigate to each microservice, and run the following command
$ ibmcloud dev deployOnce the deployment is successfully completed, you can access the portal on port 30060 of your ICP's IP address.
The Support microservice connects to an instance of Watson Assistant on IBM Cloud to simulate a chat with a virtual support agent. This is an optional step. You only need to continue if you'd like to enable the Support feature in the app.
- Create an instance of Watson Assistant
- Get your credentials
- Configure your environment variables
- Deploy
From the IBM Cloud Catalog, choose Watson Assistant, and click Create.
Navigate to the Credentials tab and copy your credentials.
From within the support folder, edit your .env to include your newly acquired credentials.
Re-deploy the Support microservice, the support feature should now be accessible through the portal.
$ ibmcloud dev deploy- Trouble with IBM Cloud CLI? See their Troubleshooting Documentation.
- Trouble with IBM Cloud Private? See their Troubleshooting Documentation
- IBM Cloud Private on local VM not working? Check the ICP version, Vagrant version and VirtualBox version carefully. Update them if necessary. If all else fails,
vagrant destroyandvagrant upagain to reset the cluster.
- Containers Code Patterns: Enjoyed this Code Pattern? Check out our other Container Code Patterns.
- IBM Cloud Private Code Patterns: Enjoyed this Code Pattern? Check out our other IBM Cloud Private Code Patterns
- Kubernetes on IBM Cloud: Deliver your apps with the combined the power of Kubernetes and Docker on IBM Cloud
Additional documentation of all the backend endpoints is available in DOCS.md.
This code pattern is licensed under the Apache Software License, Version 2. Separate third party code objects invoked within this code pattern are licensed by their respective providers pursuant to their own separate licenses. Contributions are subject to the Developer Certificate of Origin, Version 1.1 (DCO) and the Apache Software License, Version 2.