Authors: Jorge D. Rodriguez, Michele Chilanti
Reviewers: Nate Rykal, Michele Chilanti
With the introduction of technologies such as Hyperledger Fabric, companies have been able to usher a new era in application development. The decentralized nature of the technology, the shared ledger capabilities, and the ability to create immutable records that are appended to the ledger based on consensus algorithms have allowed architects and developers alike to implement solutions that can deliver workflows that are more integrated, secure and streamlined across entire business ecosystems.
A lot of effort has been placed by the opensource community and by companies into developing tools and frameworks that facilitate the creation of these blockchain networks; one great example is the world renowned and award winning IBM Blockchain Platform. However, when developers confront the task of creating business logic that needs to connect and interact with those Blockchain networks, they are left with virtually no options available to simplify their development efforts. Developers are exposed to complex and tedious aspects such as managing connection configuration, credentials, and identity mapping.
The Blockchain Open Liberty Stack for Appsody addresses those pain points, by allowing developers to easily create, package and deploy microservices that connect, query and execute transactions over a Hyperledger Fabric network of choice. This Appsody stack, currently in proof of concept state, delivers the building blocks for creating REST-based integration APIs that facilitate the connectivity between blockchain networks and existing enterprise systems, systems of record, and in-house solutions. Developed with already built-in best practices, Blockchain Open Liberty Stack provides application architects and developers with a starting point to create their own set of REST APIs as a front-end for blockchain transactions; this stack has been designed to speed up dramatically the delivery of blockchain solutions, bridge the exchange of information between external systems and the network, and shorten the time needed to deliver business value.
Blockchain Open Liberty Stack for Appsody can fast track the development of blockchain microservices by providing the following capabilities:
- Simple Open Liberty based scaffolding to create micro-service style REST APIs.
- Fully functional out of the box REST service when integrated with the IBM Blockchain Platform VS Code Extension smart contract samples.
- Modular wallet management with default implementation to manage keys and certificates used by the microservice.
- Network connection management to handle runtime connectivity between the micro-service and Hyperledger Fabric components.
- Pluggable connection profile architecture that allows connectivity to the network of choice.
- Integrated Swagger API Documentation.
- Out of the box test case coverage for API capabilities.
While the Blockchain Open Liberty Stack for Appsody is still a proof of concept, it already has all the capabilities listed above and can be used as a starting point to accelerate the development of your own projects. The following section outlines the steps required to configure and run a microservice based on the Blockchain Open Liberty Stack for Appsody and connect it with a Hyperledger Fabric network created using the IBM Blockchain Platform VS Code Extension.
First let's install the tools that we need to be able to run both the stack and the Hyperledger Fabric based network locally on a system.
- Install the IBM Blockchain Platform VS Code Extension.
- Install the Appsody command line for your operating system.
Create Hyperledger Fabric Network
Before deploying an instance of the Blockchain Open Liberty Stack, let's create a Hyperledger Fabric network using the IBM Blockchain Platform VS Code Extension. This is the network that we will use to connect our instance of the microservice. Once the network is created we also need to deploy the sample smart contract provided by the IBM Blockchain Platform VS Code Extension. This sample smart contract provides the various transactions and queries called from the Blockchain Open Liberty Stack APIs.
- Create a smart contract using the IBM Blockchain Platform VS Code Extension. Notice that the smart contract can be implemented in any of the languages supported by the IBM Blockchain Platform VS Code Extension. If you are not familiar with this process you can follow the Creating a Smart Contract Tutorial.
- Bootstrap a Hyperledger Fabric network using the IBM Blockchain Platform VS Code Extension and deploy the smart contract created in the previous step. If you are not familiar with this process you can follow the Deploying a Smart Contract Tutorial.
Register Appsody Stack
Now that we have installed the necessary tools and bootstrapped a Hyperledger Fabric network, let's package the Blockchain Open Liberty Stack and make it available for the Appsody command line to use.
- Clone the appsody-stacks project from the IBM-Blockchain github organization.
git clone https://github.com/IBM-Blockchain/appsody-stacks.git
- Navigate to appsody-stacks/incubator/blockchain-client-openliberty and issue the Appsody's package command.
appsody stack package
Initialize Microservice Project
Now that our Appsody stack has been registered with the local Appsody stack registry, let's create a project based on the Blockchain Open Liberty Stack. This project will be the starting point for our microservice.
- Create directory where the project will be initialized. The name of the directory will become the name of the project hence it is important to choose a meaningful name. I personally like to associate the name of the project with the name of the smart contract that it will be calling. For example, if the name of the smart contract is MyAsset, the project name can be MyAssetMicroservice.
- Initialize project based on the Blockchain Open Liberty Stack
appsody init dev.local/blockchain-client-openliberty
Once the appsody init
command completes successfully, the directory is populated with the framework and resources defined in the Blockchain Open Liberty Stack. This is the code that developers get to run and customize.Import Hyperledger Fabric Identities into Microservice Project
In order to access information and have the right permissions over resources in the blockchain network, our microservice needs a valid Hyperledger Fabric identity from the network we created in the previous steps. The Blockchain Open Liberty Stack allows you to either specify the identity directly via an environment variable or by providing the directory where the identity can be loaded at runtime.
Since the IBM Blockchain Platform VS Code Extension provides a convenient way to easily export identities from the Hyperledger Fabric network, we are going to export these identities and copy them into our microservice project so that they can be picked up by the microservice at runtime. The Blockchain Open Liberty Stack is implemented so that identities are picked up from the <project-name>/src/main/resources directory hence all exported identities must be copied into that directory.
If you are not familiar with how to export identities using the IBM Blockchain Platform VS Code Extension, see the Export the network details section of the Invoking a smart contract from an external application tutorial. Specifically follow sections A5.4 and A5.5 but use <name-of-smartcontract>Microservice/src/main/resources as the directory where the identities are to be exported and keep Org1 as the name of the subdirectory that will contain the identities as opposed of Org1Wallet.
At the end of this step you should have the following directory structure in the microservice project.
Verify Connection Profile
The Blockchain Open Liberty Stack comes with a preconfigured Hyperledger Fabric connection profile that matches the configuration of the blockchain network created by the IBM Blockchain Platform VS Code Extension. However, you can replace this connection profile in order to connect to other blockchain networks or you can make modifications to the default connection profile so that it better describes the characteristics of the blockchain network where the microservice is connecting.
The default connection profile can be found in the following location:
No changes are necessary if you are connecting to the blockchain network created in previous step.
Specify the Smart Contract Name
The Blockchain Open Liberty Stack allows you to specify common configuration parameters for the microservice via environment variables including the name of the smart contract that the microservice will be calling. All of these parameters and their default values can be found on the following location:
The environment variable that is used to indicate the name of the smart contract and its default value is as following:
Change the value to match the name of the smart contract deployed on previous steps via the IBM Blockchain Platform VS Code Extension.
Explore Other Properties
Other configuration parameters that can be specified via environment variables and their default values include the following:
You can change things such as the channel name that the microservice will be connecting to or the name of the identity used to connect to the network. For more details on each of these parameters see the Required Environment Variables section of the Blockchain Open Liberty Stack documentation.
Run the Microservice
Now that we have configured the microservice to properly communicate with the blockchain network and the smart contract deployed using the IBM Blockchain Platform VS Code Extension, we are ready to run the microservice. To run the microservice we will be using once again the Appsody command.
appsody run --network Local_network --docker-options "--env-file=blockchain.env"
The appsody run command will package the microservice project into a docker image and will run the microservice into the local docker containerized environment. Notice that all the configuration parameters listed in the <name-of-smartcontract>Microservice/blockchain.env file are passed as environment variables to the running container. It is worth noting that the --network flag is used to indicate the docker network that the microservice container should be attach to. This will guarantee that the microservice will be able to communicate with the Hyperledger Fabric components via the docker network.
Explore the APIs
The Blockchain Open Liberty Stack provides a Swagger UI to explore and test the APIs implemented by the microservice. Once the microservice is running you should be able to access the Swagger UI via the following endpoint:
Although the Blockchain Open Liberty Stack provides a convenient starting point to create microservices that can connect to blockchain networks, the base API implementation is tightly coupled with the sample smart contract provided by the IBM Blockchain Platform VS Code Extension. Chances are that to create more useful applications, you will have to add additional APIs, modify the data model used by existing calls and/or add support for additional transactions and queries. These kinds of modifications are confined within the application.api Java package where all the elements of a model view controller pattern have been implemented through MyAsset.java, AssetService.java and MyAssetController.java respectively. Customizing your APIs will require modifications in any of those Java resources.
The Blockchain Open Liberty Stack provides a modular framework that can be enhanced to meet the requirements of your microservice implementation. Some of the updates that can easily be implemented include adding new identity wallets to store Hyperledger Fabric credentials and updating the identity mapping logic to associate authenticated API users to Hyperledger Fabric identities. To implement a new identity wallet, look at the WalletManager.java resource in the application.utils package and the FilesystemWallet.java implementation. To map authenticated API users to Hyperledger Fabric identities look at the IdentityMapperFilter.java resource in the application.api package. Additional information on how to customize the Blockchain Open Liberty Stack can be found in the stack documentation.
Let us know what you think! Is this implementation useful? What other capabilities or changes would you like to see? Use the comment section to provide feedback!