This project provides is a Reference Implementation for building an OmniChannel Application using a microservices architecture. The Logical Architecture for this reference implementaiton is shown in the picture below.
The application is a simple Shopping Application that displays a List of Inventory as well as a Social Review. Both the Mobile App and Web App rely on separate Microservices to retrieve the Inventory data along with the review.
There are several components of this architecture.
- This OmniChannel application contains both a Native iOS Application and an angular based web application. The diagram depicts them as a Device and Browser.
- The iOS application uses the IBM Mobile Analytics Service to collect device analytics for operations and business
- Both Client Applications make API calls through an API Gateway. The API Gateway is API Connect. API Connect provides an OAuth Provider as well, allowing you to implement API Security.
- The API's are implemented as Node JS Microservices, we call BFFs Backend for Frontends. In this Layer, front end developers usually write backend logic for their front end. The Inventory BFF is implemented using the Express Framework. The Social Review BFF is implemented using API Connect's loopback framework. These Microservices run in Bluemix as CloudFoundry Applications.
- The Node JS BFFs invoke another layer of reusable Java Microservices. In a real world project, this is sometimes written by a different team. These reusable microservices are written in Java using SpringBoot. They run inside IBM Containers using Docker.
- Node BFF's and Java Microservices communicate to each other using the Netflix OSS Framework. In this case, we run several Netflix components in Bluemix.
- Zuul provides a proxy layer for the microservices.
- Eureka provides a Service Registry. The reusable Java Microservices register themselves to Eureka which allows clients to find them.
- Hystrix Provides an implementation of the Circuit Creaker Pattern. This component runs as library inside the Java Applications. This component them forward Service Availability information to the Hystrix Dashboard.
- The Java Microservices retrieve their data from databases. The Inventory Application using MySQL. In this example, we run MySQL in a Docker Container for Development (In a production environment, it runs using our Infrastrcuture as a Service) The resilliency and DevOps section will explain that. The SocialReview Java Microservice relies on Cloudant as its Database.
This project runs itself like a microservice project, as such each component in the architecture has its own Git Repositoy and tutorial listed below.
- refarch-cloudnative - The root repository (Current repository)
- refarch-cloudnative-bluecompute-mobile - The BlueCompute client iOS application
- refarch-cloudnative-bluecompute-web - The BlueCompute client Web application
- refarch-cloudnative-bff-inventory - The cloud Foundry node.js app for Inventory bff
- refarch-cloudnative-bff-socialreview - The cloud Foundry node.js app for SocialReview bff
- refarch-cloudnative-api - The API gateway artifacts
- refarch-cloudnative-auth - The security/OAauth artifact
- refarch-cloudnative-micro-inventory - The microservices (SpringBoot) app for Inventory data service (MySQL)
- refarch-cloudnative-micro-socialreview - The microservices (SpringBoot) app for SocialReview data service (Cloudant)
- microservices-netflix-eureka - Contains the Eureka containers for Microservices foundation
- microservices-netflix-zuul - Contains the Eureka containers for Microservices foundation
- refarch-cloudnative-mysql - The MySQL Docker container and database DDL
This project contains tutorials for setting up CI/CD pipleine for the scenarios. The tutorial is shown below.
- refarch-cloudnative-devops - The DevOps assets will be managed here
This project contains tutorials for setting up Resiliency such as High Availablity, Failover, and Disaster Recovery for the above application.
- refarch-cloudnative-resiliency - The Resiliency Assets will be managed here
To run the sample applications you will need to configure your Bluemix enviroment for the API and Microservices runtimes. Additionally you will need to configure your system to run the iOS and Web Application tier as well.
- Install Java JDK 1.8 and ensure it is available in your PATH
- Install Node.js version 0.12.0 or version 4.x
- Install Docker on Windows or Mac
- Login to your Bluemix account or register for a new account here
In order to complete the rest of this tutorial, many commands will require the Bluemix CLI toolkit to be installed on your local environment. To install it, follow these instructions
This walkthrough uses the cf
tool.
- Click on the Bluemix account in the top right corner of the web interface.
- Click Create a new space.
- Enter "cloudnative-dev" for the space name and complete the wizard.
-
Clone the base repository:
git clone https://github.com/ibm-cloud-architecture/refarch-cloudnative
-
Clone the peer repositories:
./clonePeers.sh
After completing this step, you should have Inventory microservice deployed in Bluemix and interacting with MySQL database. You can unit test the microservice as documented in the instruction.
-
Setup MySQL
Please follow the instruction in refarch-cloudnative-mysql repository to setup the MySQL database. -
Build and Deploy the Inventory microservice Please follow the instruction in refarch-cloudnative-micro-inventory repository to setup the MySQL database.
After completing this step, you should have SocialReview microservice deployed in Bluemix and interacting with hosted Cloudant database. You can unit test the micorservice as documented in the instruction.
Please follow the instruction in refarch-cloudnative-micro-socialreview repository to setup the Cloudant database and build/deploy the microservice to Bluemix.
We used the Netflix OSS stack to provide some of the microservices foundation services such as service registry and proxy/load balancer. Specifically, we use the Eureka as registry and Zuul as proxy.
Please follow the instruction in microservices-netflix-eureka repository to deploy Eureka to Bluemix.
Please follow the instruction in microservices-netflix-zuul repository to deploy Zuul to Bluemix.
- Click on the Bluemix console and select API as shown in the figure below.
- Select the API Connect service as shown below.
- Click "Create" in the Getting Started with API Connect page. In API Connect creation page, specify the Service name anything you like or keep the default. Then select the free Essentials plan for this walkthrough.
- After the API Connect service is created, launch the API Connect service by clicking "Launch API Manager"
- In the API Manager page, navigate to the API Connect Dashboard and select "Add Catalog" at the top left. You may notice that a sandbox has automatically been generated for you.
- Name the catalog "BlueCompute" and press "Add".
- Select the catalog and then navigate to the Settings tab and click the Portal sub-tab.
- To setup a Developer Portal that your consumers can use to explore your API, select the IBM Developer Portal radio button. Then click the "Save" button to top right menu section. This will provision a portal for you. You should receive a message like the one below.
- Once the new Developer Portal has been created, you will receive an email.
The IBM API Connect Developer Toolkit provides both the API Designer UI and a CLI that developers can use to develop APIs and LoopBack applications, as welll as the tools to publish them to the IBM API Connect runtime.
Before getting started, you will need to install Node.js version 0.12 or version 4.x, follow the link below for more information details. https://www.ibm.com/support/knowledgecenter/en/SSFS6T/com.ibm.apic.toolkit.doc/tapim_cli_install.html
To install the APIC Connect CLI:
$ npm install -g apiconnect
$ apic -version
That should install the tool and print the version number after the last command.
This bff application will proxy (through Zuul) to the inventory microservice. It also exposes services to IBM API Connect for the Mobile and Web application to consume.
Please follow the instruction in refarch-cloudnative-bff-inventory repository to build/deploy the Inventory Node.js application to Bluemix Cloud Foundry runtime.
This Loopback application will proxy (through Zuul) to the SocialReview microservice. It also exposes services to IBM API Connect for the Mobile and Web application to consume.
Please follow the instruction in refarch-cloudnative-bff-socialreview repository to build/deploy the SocialReview Loopback application to Bluemix Cloud Foundry runtime.
Once you have the backend application deployed, it is time to publish the APIs to the IBM Bluemix API connect and Setup developerPortal to consume the API.
Please follow the instruction in refarch-cloudnative-api repository to publish APIs to Bluemix API Connect runtime.
Time to test the application end-to-end. You can start with running the iOS application to integrate with the APIs as well as monitoring the application using Bluemix Mobile Analytics service.
Please follow the instruction in refarch-cloudnative-bluecompute-mobile repository to setup your iOS application.
You can also validate the omnichannel implementation of the solution by running the BlueCompute Web application.
Please follow the instruction in refarch-cloudnative-bluecompute-web repository to setup your Web application.