Contents


Deploy a blockchain business network to the cloud using the IBM Blockchain Starter Plan

The easy way to launch a pre-production network and run your first application on it

Comments

In this tutorial, you'll deploy an existing sample business network, the Car Auction network, to the cloud, specifically to the IBM Blockchain Platform Starter Plan. Once you deploy the sample network, you can start developing, demoing, and staging your blockchain applications on a simulated multi-organization network.

This tutorial is neither about Hyperledger Fabric, which serves as the underlying implementation of the IBM Blockchain Platform, nor about Hyperledger Composer, which provides a modern toolset to build business networks and applications rapidly. Hyperledger Composer exposes a business model and abstracts away the complexities involved.

This tutorial IS about deploying an existing sample business network created using Hyperledger Composer to the Starter Plan instance available on the IBM Cloud.

Learning objectives

  • Create a wallet in the IBM Cloud using the Cloudant NoSQL Database service.
  • Deploy the Car Auction sample network to the IBM Cloud.
  • Start the sample network.
  • Expose REST APIs from the cloud for the deployed sample network.
  • Generate and run an Angular app that uses the REST APIs.

Time to complete this tutorial

  • Approximately 45 minutes.

Prerequisites

You need the following software installed locally:

Let's get started

For this exercise, let's deploy the hugely popular sample Car Auction network (built using Hyperledger Composer) to the Starter Plan instance. This image shows the participants, assets, and typical transactions on this sample network:

Hyperledger Composer enables you to rapidly build business networks and applications. To build a business network, you need to define a business model in a .cto file, which contains the following:

  • Participants
  • Assets
  • Transactions

In the Car Auction network, the participants are represented in the business model using the Auctioneer and Member types as shown:

abstract participant User identified by email {
  o String email
  o String firstName
  o String lastName
}

participant Member extends User {
  o Double balance
}

participant Auctioneer extends User {
}

Similarly, assets are represented in the Car Auction network using the types Vehicle and VehicleListing as shown:

enum ListingState {
  o FOR_SALE
  o RESERVE_NOT_MET
  o SOLD
}

asset Vehicle identified by vin {
  o String vin
  --> Member owner
}

asset VehicleListing identified by listingId {
  o String listingId
  o Double reservePrice
  o String description
  o ListingState state
  o Offer[] offers optional
  --> Vehicle vehicle
}

And transactions are represented in the Car Auction network by the types Offer and CloseBidding as shown:

transaction Offer {
  o Double bidPrice
  --> VehicleListing listing
  --> Member member
}

transaction CloseBidding {
  --> VehicleListing listing
}

To exchange ownership of assets, participants submit transactions on the business network.

1

Set up your local environment

  1. To deploy the existing Car Auction network to the IBM Cloud, you need the following software installed locally, as mentioned previously:
  2. If you've already been playing with Hyperledger Composer, then you should first uninstall and re-install Hyperledger Composer 0.19.5, which is compatible with the Starter Plan instance, as shown:
    $ rm -rf ~/.composer 
    $ npm uninstall -g composer-cli 
    $ npm uninstall -g generator-hyperledger-composer 
    $ npm uninstall -g @ampretia/composer-wallet-cloudant 
    $ npm install -g composer-cli@0.19.5 
    $ npm install -g generator-hyperledger-composer@0.19.5 
    $ npm install -g @ampretia/composer-wallet-cloudant
  3. Next, you should clone the GitHub repo that contains the artifacts for the Car Auction network as shown:
    $ cd ~/Workdir
    $ git init business-networks
    $ cd business-networks
    $ git remote add -f origin https://github.com/hyperledger/composer-sample-networks
    $ git config core.sparseCheckout true
    $ echo "packages/carauction-network/" >> .git/info/sparse-checkout
    $ git pull origin master

At this point, the artifacts for the Car Auction network should be available in the ~/Workdir/business-networks/packages/carauction-network folder. This folder will serve as the root folder. From there, you will execute the commands to build and deploy the business network to the Starter Plan instance.

2

Launch the IBM Blockchain Starter Plan instance on the IBM Cloud

  1. Create an IBM Cloud account, if you don't have one already.
  2. Once you have an account, launch the Starter Plan instance as shown:
  1. When the Starter Plan instance is up and running, you can monitor the organizations and the peers that are set up by default for you. Typically, you will have two organizations each with a Certificate Authority, Ordering Service, and Endorsing/Validating peer. To look at these elements, you can switch between the organizations using the drop-down under the profile icon on the top-right corner, as shown:

The resulting distributed ledger of transactions will be stored on the peers in each organization. For more details, see the Hyperledger Fabric documentation.

  1. For the next set of steps, we will use the Connection Profile for Company A (org1). So, select Company A in the top-right corner before you start the next set of steps.
3

Download the Connection Profile

  1. Download the Connection Profile for Company A (org1) to your local filesystem, as shown:
  1. Note the value of the enrollSecret property from the raw JSON. (You can also get the value of the enrollSecret property from the downloaded JSON file by opening it up in an editor and searching for enrollSecret.) You will use the enrollSecret value in subsequent steps to create certificates and more.
  2. Rename and copy the downloaded json file to the root folder that was setup in the earlier steps as shown:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ mv ~/Downloads/creds_*_org1.json connection-profile.json
4

Create Cloudant NoSQL DB Service

Since we are planning on exposing the REST APIs for the business network from the cloud, we have to use a cloud-based wallet to store the cards that we will be creating with Hyperledger Composer.

  1. In order to store the wallet with cards in the cloud, you should install composer-wallet-cloudant node module, if you have not installed during the earlier steps, as shown:
    $ npm install -g @ampretia/composer-wallet-cloudant
  2. You should create a file named cardstore-cloudant.json in ~/Workdir/business-networks/packages/carauction-network directory with the following content:
    {
      "composer": {
        "wallet": {
          "type": "@ampretia/composer-wallet-cloudant",
          "options": {
            "database": "composer-wallets",
          }
        }
      }
    }

    Note the name of the database composer-wallets that is specified in cardstore-cloudant.json file. This will be used when creating a database next. You can choose a different name for the database as long as it is the same as the one specified in cardstore-cloudant.json file.

  3. To keep things simple, create Cloudant NoSQL service in the same region, org, and space as the Starter Plan instance. Also, create a database named composer-wallets within the Cloudant NoSQL service as shown:
  1. Once the Cloudant NoSQL service and the database are created successfully, create the service credentials and update cardstore-cloudant.json with the credentials as shown:

At this point, cardstore-cloudant.json should contain the credentials for Hyperledger Composer to access Cloudant NoSQL DB service and populate the composer-wallets database with cards that will created in the next steps.

  1. Export NODE_CONFIG environment variable as shown below:
    $ export NODE_CONFIG=$(cat cardstore-cloudant.json)

From this point on, all the subsequent commands must be executed in the same Terminal window/tab in which enviroment variable NODE_CONFIG was set to ensure that the cloud-based wallet is populated with the necessary cards.

5

Create the Certificate Authority Card

  1. Using the connection-profile.json and the enrollSecret value that you noted in one of the earlier steps create a Certificate Authority card for Company A (org1) as shown, replacing <your-enrollSecret> with the value that you noted earlier:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer card create -f ca.card -p connection-profile.json -u admin -s <your-enrollSecret>
  2. Import the newly created card as shown:
    $ composer card import -f ca.card -c ca
  3. With the card containing the enrollSecret successfully imported, request the valid public/private keys for the admin from the Certificate Authority as shown:
    $ composer identity request --card ca --path ./credentials

At this point, ~/Workdir/business-networks/packages/carauction-network/credentials should contain the public and private keys for the admin.

6

Add a certificate to the Starter Plan

Initially, the Starter Plan instance does not have any certificates in the Members node, as you can see:

  1. Click on the Channels node on the left to see that the Block Height is 3, indicating the number of transactions that have been performed behind the scenes so far. Click on 3 to poke around to see the GENESIS block and check the details for each of the invocations.
  2. Open the public key for the admin located in ~/Workdir/business-networks/packages/carauction-network/credentials/admin-pub.pem in an editor and copy its contents to the clipboard. You will add this public key to the Starter Plan instance, as shown:
  1. Once the public key is added, you need to sync the certificate across peers using the Channels node, as shown:
  1. Click the Submit button to complete the process of syncing the certificate. At this point, if you go back and look at the Channels node, you will see that the Block Height has been updated to 4. This indicates that every change to the environment is also tracked as a transaction in the immutable distributed ledger.
7

Create and import a business network card for the admin

With certificates synced across peers, you can create business network cards to install Hyperledger Composer and then deploy/start the chaincode or the business network on the Starter Plan instance.

Create an admin card with channel admin and peer admin roles, and then import the newly created card as shown:

$ cd ~/Workdir/business-networks/packages/carauction-network
$ composer card create -f adminCard.card -p connection-profile.json -u admin \
    -c ./credentials/admin-pub.pem -k ./credentials/admin-priv.pem \
    --role PeerAdmin --role ChannelAdmin
$ composer card import -f adminCard.card -c adminCard
8

Install and start the business network

In this step, you'll use the adminCard created in the previous step, with privileges to install and start a business network, to install the Car Auction network to the Starter Plan instance.

  1. To be able to install and start a business network, you need to first create a Business Network Archive (.bna) file by zipping up the necessary artifacts as shown:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer archive create -t dir -n .
  2. This will result in the creation of carauction-network@0.x.y.bna file, where @0.x.y represents the version specified in the package.json file. Since the Starter Plan instance does not accept files with @ in the name, rename the file as shown:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ mv carauction-network@*.bna carauction-network.bna
  3. Install the business network and the Hyperledger Composer runtime to the Starter Plan instance as shown:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer network install -c adminCard -a carauction-network.bna
  4. If the previous step fails, then wait for a few seconds and give it another shot.
  5. Once the runtime and the business network are successfully installed, start the business network on the Starter Plan instance as shown. Instead of the 0.2.4, specify the version number that is specified in your package.json file:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer network start -c adminCard -n carauction-network -V 0.2.4 \
      -A admin -C ./credentials/admin-pub.pem -f delete_me.card

    You may run into sporadic issues such as REQUEST_TIMEOUT. Once again, wait for a few seconds and try again. In addition to starting the business network, the previous command also uses the -A switch to specify the id of the network-administrator who will be responsible for creating participants and other bookkeeping actions for the specific network.

  6. Once the command is successful, check the Block Height under the Channels node in the UI to see it updated to 5, as well as details about the newly installed/started Car Auction network.
  7. Delete the redundant delete_me.card that was generated by the previous command as shown:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ rm delete_me.card
9

Create a card for the network administrator

While starting the business network in the previous section, we used the -A command-line argument to specify the id of the network administrator who will be responsible for running the network by issuing identities and such to other participants on the network. Let’s create the business network card for the network-admin.

  1. To create the business network card for the network admin, use the following command:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer card create -n carauction-network -p ./connection-profile.json \
        -u admin -c ./credentials/admin-pub.pem -k ./credentials/admin-priv.pem
  2. Import the card using the following command:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ composer card import -f admin@carauction-network.card

At this point, the business network is operational on the Starter Plan instance.

10

Expose REST APIs in the cloud for the business network

Once the business network is running on the Starter Plan instance, you can run composer-rest-server as a Cloud Foundary application in the cloud to generate and expose REST APIs directly in the cloud thereby allowing web as well as mobile/native apps to exercise them. Make sure that NODE_CONFIG environment variable is set and then execute the following commands to expose the REST APIs in the cloud:

$ cf login -a https://api.ng.bluemix.net --sso
$ cf push car-auction --docker-image ibmblockchain/composer-rest-server:0.19.5 \
    -c "composer-rest-server -c admin@carauction-network -n never -w true" \
    -i 1 -m 256M --no-start --no-manifest
$ cf set-env car-auction NODE_CONFIG "${NODE_CONFIG}"
$ cf start car-auction

The cf start car-auction command will take some time to complete. Eventually, you should see the following output in your Terminal:

Starting app car-auction in org Sanjay-Bluemix / space dev as ...
Creating container
....
Successfully destroyed container

0 of 1 instances running, 1 starting
...
1 of 1 instances running
0 of 1 instances running, 1 starting
...
1 of 1 instances running

App started

OK

App car-auction was started using this command `composer-rest-server -c admin@carauction-network -n never -w true`

Showing health and status for app car-auction in org Sanjay-Bluemix / space dev as ...
OK

requested state: started
instances: 1/1
usage: 256M x 1 instances
urls: car-auction.mybluemix.net
last uploaded: Mon May 21 16:12:14 UTC 2018
stack: cflinuxfs2
buildpack: unknown

     state     since                    cpu     memory           disk         details
#0   running   2018-05-21 09:19:39 AM   16.8%   154.9M of 256M   1.3M of 1G

Note the URL https://car-auction.mybluemix.net in the output above. You can point your browser to https://car-auction.mybluemix.net to browse and exercise the REST APIs to create new participants and assets, and submit transactions while watching the Block Height under Channels node grow. If you look at the auction.cto file that defines the business model of the Car Auction network, you will recall that participants are represented by Auctioneer and Member types; assets are represented by Vehicle and VehicleListing types; and transactions are defined using Offer and CloseBidding types.

This video shows the REST APIs being exercised using the JSON payload:

In the above video, you can see the following participants being created:

  • Bobby Da Boss with email bobby.da.boss@example.com is created as an Auctioneer to run the auction.
  • James Bond with a balance of $1000 and email address james.bond@example.com is created as a Member.
  • Jason Bourne with a balance of $2000 and email address jason.bourne@example.com is created as a Member.
  • Bruce Wayne with a balance of $5000 and email address bruce.wayne@example.com is created as a Member.

After creating each of these participants, you can see the Block Height under the Channels node increasing as the changes are recorded as transactions in the distributed ledger.

In the video, you will also see the following assets being created:

  • Vehicle identified by BM_001 and owned by bruce.wayne@example.com is added to the network.
  • Bruce Wayne puts up one of his Batmobiles, identified by BM_001, for sale by creating a VehicleListing identified by L1 and an asking price of $500.

Once again, after each of these actions, the Block Height under the Channels node increases.

Finally, in the video, you will also see the transactions being submitted:

  • An Offer is made on behalf of James Bond for $800.
  • An Offer is made on behalf of Jason Bourne for $1200.

Bobby Da Boss, the Auctioneer, will submit a CloseBidding transaction eventually. And, you can see the ownership of the Batmobile change from bruce.wayne@example.com to jason.bourne@example.com. You will also see the $1200 added to Bruce Wayne's balance. And, the same amount deducted from Jason Bourne's balance.

You will also see the Block Height increasing with transactions being submitted by the participants and the assets exchanged. Each of these changes is recorded as a transaction in the distributed ledger that is stored on the peers in the two organizations. You can observe the Block Height grow after a change is made as shown in the above video.

11

Generate an Angular app for the business network

You can exercise the REST endpoints generated in the previous step by an Angular app generated using the Yeoman generator.

  1. Install generator-hyperledger-composer and yo as shown:
    $ npm install -g generator-hyperledger-composer
    $ npm install -g yo
  2. You should be in the root directory that contains connection-profile.json to generate the Angular app. Also, you should use the URL https://car-auction.mybluemix.net as the REST server address and 443 as REST server port as shown below:
    $ cd ~/Workdir/business-networks/packages/carauction-network
    $ yo hyperledger-composer:angular
    
    Welcome to the Hyperledger Composer Angular project generator
    ? Do you want to connect to a running Business Network? Yes
    ? Project name: angular-app
    ? Description: Hyperledger Composer Angular project
    ? Author name: foo
    ? Author email: foo@example.com
    ? License: Apache-2.0
    ? Name of the Business Network card: admin@carauction-network
    ? Do you want to generate a new REST API or connect to an existing REST API?  Connect to
    an existing REST API
    ? REST server address: https://car-auction.mybluemix.net
    ? REST server port: 443
    ? Should namespaces be used in the generated REST API? Namespaces are not used
    Created application!

    This will generate an application in the angular-app folder.

12

Run the Angular app

To run the generated Angular app do the following:

$ cd ~/Workdir/business-networks/packages/carauction-network
$ cd angular-app
$ npm start

The app will be compiled, and you can eventually interact with it by pointing your browser to http://localhost:4200. This video shows the Vehicle and VehicleListing assets that were created and updated using the REST APIs directly as part of the previous section:

Conclusion

You now know how to use Blockchain-as-a-Service in the Starter Plan on the IBM Cloud. You're ready to take advantage of deploying your own business networks, so that you can take 'em out for a spin. And, once you're satisfied, you can seamlessly move your deployment to the Enterprise Plan.

Next steps

  • Now that you've deployed a sample network, learn how to create business networks from scratch using Hyperledger Composer in our popular series, Hyperledger Composer basics, by Steve Perry.
     
  • Stay in the know with the monthly Blockchain Newsletter for developers. Check out the current issue and subscribe.
     
  • Check out the many code patterns, which provide roadmaps for solving complex problems with blockchain technology, and include architecture diagrams, code repos, and additional reading.
     
  • Stop by the Blockchain Developer Center. It's your source for free tools and tutorials, along with code and community support, for developing and deploying blockchain solutions for business.

About the author

Sanjay Saxena is an IBM Senior Technical Staff Member and Developer Advocate for the IBM Cloud. He is currently focused on emerging technologies such as Blockchain, IoT, AR/VR, and Jupyter/Spark. Sanjay has more than two decades of system development experience, including MVC-based metadata-driven application development frameworks, real-time communications, pub/sub messaging across Java, C#, Objective-C, and JavaScript. A husband and father of two, Sanjay enjoys skiing, STEM, and mixing flavors and spirits for the perfect cocktail.


Downloadable resources


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Blockchain, Cloud computing
ArticleID=1060487
ArticleTitle=Deploy a blockchain business network to the cloud using the IBM Blockchain Starter Plan
publish-date=06212018