How to setup and build Hyperledger Fabric Blockchain Applications

This is an introduction to how to configure and launch the Hyperledger Fabric v1.0 permissioned blockchain network on an Ubuntu 16.04 Virtual Machine on AWS.

If you want to skip configuring the VM/images check out the IBM Bluemix Fabric managed service: https://console.ng.bluemix.net/catalog/services/blockchain/

Below is the command line steps in addition to links to additional guides on configuring your network.

The first part of this article is focused on the infrastructure layer, Hyperledger Fabric.

The second part of this article is focused on the application layer, Fabric Composer.

You can spin up the latest versions of Fabric V1 and use the shell scripts for standup and teardown of the network in the second part.

The Infrastructure Layer

Creating your VM on AWS

The first thing you are going to do is go to AWS and create a new account:

Go to https://aws.amazon.com/

Create your account and you will need to create a support request to increase the number of EC2 instances you can have.

Once your limit has increased you will launch a new EC2 Virtual Machine using the Launch Wizard.

Choose your Instance Type: c3.large

Go through the configuration screens and add storage to your VM 8/32/64 GB should work.

Once this has been done go to the Launch screen and generate a new key-pair for this Virtual Machine.

You will download the key pair and put it in some folder on your local machine.

Next the instance will launch and you will be able to see on your dashboard.

Copy the URL from your Virtual Machine

Open Git on your machine and go to the directory where you have downloaded the key to your Virtual Machine.

then ssh -i ./yourkeyname.pem ubuntu@yoururlname

once you have sshed in, you are now able to use the Virtual Machine.

The below is the exact steps or you can continue to the more verbose version in the rest of the article.

This is the exact step by step way to do it in less then 20 minutes:


sudo apt-get update
wget https://storage.googleapis.com/golang/go1.7.4.linux-amd64.tar.gz
sudo tar -xvf go1.7.4.linux-amd64.tar.gz
sudo apt-key adv –keyserver hkp://p80.pool.sks-keyservers.net:80 –recv-keys 58118E89F3A912897C070ADBF76221572C52609D
sudo apt-add-repository ‘deb https://apt.dockerproject.org/repo ubuntu-xenial main’
sudo apt-get install -y docker-engine
sudo curl -o /usr/local/bin/docker-compose -L “https://github.com/docker/compose/releases/download/1.11.2/docker-compose-$(uname -s)-$(uname -m)”
sudo chmod +x /usr/local/bin/docker-compose
mkdir ~/fabric-tools && cd ~/fabric-tools
curl -O https://raw.githubusercontent.com/hyperledger/composer-tools/master/packages/fabric-dev-servers/fabric-dev-servers.zip
sudo apt install unzip
unzip fabric-dev-servers.zip
curl -O https://hyperledger.github.io/composer/prereqs-ubuntu.sh
chmod u+x prereqs-ubuntu.sh
./prereqs-ubuntu.sh
cd fabric-tools
./downloadFabric.sh
./startFabric.sh
./createComposerProfile
cd..
git clone https://github.com/hyperledger/composer-sample-networks.git
cp -r ./composer-sample-networks/packages/basic-sample-network/ ./my-network
rm -rf composer-sample-networks
cd my-network
npm install
npm install -g composer-cli
npm install -g composer-rest-server
cd dist
composer network deploy -p hlfv1 -a basic-sample-network.bna -i PeerAdmin
composer-rest-server

Don’t forget to change your security groups to open inbound/outbound traffic!


 

Configuring your Virtual Machine

There are a number of packages that you are going to need to install and configure in your VM.

Install Git, Nodejs and GO

Digital Ocean Guide – Node.js

Installing GO and setting your GOPATH

*** update USE NVM for node and npm, no sudo required, will be important for your fabric composer setup ***

sudo apt-get update

sudo apt-get install git

sudo apt-get install nodejs use nvm

sudo apt-get install npm  use nvm

wget https://storage.googleapis.com/golang/go1.7.4.linux-amd64.tar.gz
$ sudo tar -xvf go1.7.4.linux-amd64.tar.gz
$ sudo mv go /usr/local
cd ubuntu
mkdir yourgodirectoryname
export GOROOT=/usr/local/go 
export GOPATH=$HOME/yourgodirectoryname
export PATH=$GOPATH/bin:$GOROOT/bin:$PATH
sudo nano ~/.profile

Add the above three commands to the bttom of the /.profile file

Install Docker 1.12 and Docker-Compose 1.18

Digital Ocean Guide

sudo apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys 58118E89F3A912897C070ADBF76221572C52609D
sudo apt-add-repository 'deb https://apt.dockerproject.org/repo ubuntu-xenial main'
sudo apt-get update

sudo apt-get install -y docker-engine

docker


sudo curl -o /usr/local/bin/docker-compose -L "https://github.com/docker/compose/releases/download/1.11.2/docker-compose-$(uname -s)-$(uname -m)"
sudo chmod +x /usr/local/bin/docker-compose
docker-compose -v

*****At this point you should have a Linux VM fully setup and you are now ready to download the docker images for the various components of your Blockchain network.****

Clone the Hyperledger Fabric v1 Images

You can download the images here and this will show you how to call chaincode directly at the command line. Later on we will use Composer to spin up docker images and write to the chain by deploying a business network archive.

Architecture Overview
All Hyperledger projects follow a design philosophy that includes a modular extensible
approach, interoperability, an emphasis on highly secure solutions, a token-agnostic
approach with no native cryptocurrency, and the development of a rich and easy-touse
Application Programming Interface (API). The Hyperledger Architecture WG has
distinguished the following business blockchain components:
• Consensus Layer – Responsible for generating an agreement on the order and
confirming the correctness of the set of transactions that constitute a block.
• Smart Contract Layer – Responsible for processing transaction requests and
determining if transactions are valid by executing business logic.
• Communication Layer – Responsible for peer-to-peer message transport between
the nodes that participate in a shared ledger instance.
• Data Store Abstraction – Allows different data-stores to be used by other modules.
• Crypto Abstraction – Allows different crypto algorithms or modules to be swapped
out without affecting other modules.
• Identity Services – Enables the establishment of a root of trust during setup of a
blockchain instance, the enrollment and registration of identities or system entities
during network operation, and the management of changes like drops, adds, and
revocations. Also, provides authentication and authorization.
• Policy Services – Responsible for policy management of various policies specified
in the system, such as the endorsement policy, consensus policy, or group
management policy. It interfaces and depends on other modules to enforce the
various policies.
• APIs – Enables clients and applications to interface to blockchains.
• Interoperation – Supports the interoperation between different blockchain instances.

 

SOURCE: https://www.hyperledger.org/wp-content/uploads/2017/08/HyperLedger_Arch_WG_Paper_1_Consensus.pdf

Getting Started

This is the Fabric Getting Started Guide and here is the end-to-end guide on Github

cd ubuntu
cd yourgodirectoryname
mkdir src
cd src
mkdir github.com
cd github.com
mkdir hyperledger
cd hyperledger
git clone https://github.com/hyperledger/fabric.git
sudo apt install libtool libltdl-dev

Download the Docker Images for Fabric v1.0

cd fabric
make release-all
make docker
docker images

You should see your docker images    (this is for x86_64-1.0.0-alpha2)

REPOSITORY TAG IMAGE ID CREATED SIZE
dev-peer0.org1.example.com-marbles-1.0 latest 73c7549744f3 6 days ago 176MB
hyperledger/fabric-couchdb latest 3d89ac4895f9 12 days ago 1.51GB
hyperledger/fabric-couchdb x86_64-1.0.0-alpha2 3d89ac4895f9 12 days ago 1.51GB
hyperledger/fabric-ca latest 86f4e4280690 12 days ago 241MB
hyperledger/fabric-ca x86_64-1.0.0-alpha2 86f4e4280690 12 days ago 241MB
hyperledger/fabric-kafka latest b77440c116b3 12 days ago 1.3GB
hyperledger/fabric-kafka x86_64-1.0.0-alpha2 b77440c116b3 12 days ago 1.3GB
hyperledger/fabric-zookeeper latest fb8ae6cea9bf 12 days ago 1.31GB
hyperledger/fabric-zookeeper x86_64-1.0.0-alpha2 fb8ae6cea9bf 12 days ago 1.31GB
hyperledger/fabric-orderer latest 9a63e8bac1f5 12 days ago 182MB
hyperledger/fabric-orderer x86_64-1.0.0-alpha2 9a63e8bac1f5 12 days ago 182MB
hyperledger/fabric-peer latest 23b4aedef57f 12 days ago 185MB
hyperledger/fabric-peer x86_64-1.0.0-alpha2 23b4aedef57f 12 days ago 185MB
hyperledger/fabric-javaenv latest a9ca2c90a6bf 12 days ago 1.43GB
hyperledger/fabric-javaenv x86_64-1.0.0-alpha2 a9ca2c90a6bf 12 days ago 1.43GB
hyperledger/fabric-ccenv latest c984ae2a1936 12 days ago 1.29GB
hyperledger/fabric-ccenv x86_64-1.0.0-alpha2 c984ae2a1936 12 days ago 1.29GB
hyperledger/fabric-baseos x86_64-0.3.0 c3a4cf3b3350 4 months ago 161MB

Create your network artifacts

cd examples
cd e2e_cli
./generateArtifacts.sh <channel-ID>

Make sure to choose a channel name for <channel-ID> ie mychannel

then the below to launch the network

CHANNEL_NAME=<channel-id> TIMEOUT=<pick_a_value> docker-compose -f docker-compose-cli.yaml up -d

or use this script to launch the network in one command.

./network_setup.sh up <channel-ID> <timeout-value>
docker ps

To manually run and call the network use

Open the docker-compose-cli.yaml file and comment out the command to run script.sh. Navigate down to the cli container and place a # to the left of the command. For example:

  working_dir: /opt/gopath/src/github.com/hyperledger/fabric/peer
# command: /bin/bash -c './scripts/script.sh ${CHANNEL_NAME}; sleep $TIMEOUT'

Save the file and return to the /e2e_cli directory.

# Environment variables for PEER0
CORE_PEER_MSPCONFIGPATH=$GOPATH/src/github.com/hyperledger/fabric/peer/crypto/peer/peer0/localMspConfig
CORE_PEER_ADDRESS=peer0:7051
CORE_PEER_LOCALMSPID="Org0MSP"
CORE_PEER_TLS_ROOTCERT_FILE=$GOPATH/src/github.com/hyperledger/fabric/peer/crypto/peer/peer0/localMspConfig/cacerts/peerOrg0.pem
docker exec -it cli bash
peer channel join -b yourchannelname.block
peer chaincode install -n mycc -v 1.0 -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02
# remember to preface this command with the global environment variables for the appropriate peer
# remember to pass in the correct string for the -C argument.  The default is mychannel
peer chaincode instantiate -o orderer0:7050 --tls $CORE_PEER_TLS_ENABLED --cafile $GOPATH/src/github.com/hyperledger/fabric/peer/crypto/orderer/localMspConfig/cacerts/ordererOrg0.pem -C mychannel -n mycc -v 1.0 -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02 -c '{"Args":["init","a", "100", "b","200"]}' -P "OR ('Org0MSP.member','Org1MSP.member')"
peer chaincode invoke -o orderer0:7050  --tls $CORE_PEER_TLS_ENABLED --cafile $GOPATH/src/github.com/hyperledger/fabric/peer/crypto/orderer/localMspConfig/cacerts/ordererOrg0.pem  -C mychannel -n mycc -c '{"Args":["invoke","a","b","10"]}'
peer chaincode query -C mychannel -n mycc -c '{"Args":["query","a"]}'

You now should have a functioning network that you can call.

To Setup and use Couch DB for richer queries follow the tutorial here.

To clean and bring down the network use 

./network_setup.sh down
sudo docker ps

you shouldn’t see any containers running.

To stop individual various containers use

sudo docker stop <name>

sudo docker rm <name>

To learn about the Hyperledger Fabric API visit http://jimthematrix.github.io/ This is a great resource for learning about the intricacies of the network and the different certificates needed for trusted transactions.

Below is the second part the Application Layer, Fabric Composer.

The Application Layer

You have configured and setup a VM, you have your docker containers running, your Hyperledger Fabric V1.0 blockchain infrastructure is live; now you want to model, build and deploy a business application on this network. This article will show you exactly how to wire up the application layer and the infrastructure layer.

You can run the network locally using npm or docker

  npm install -g composer-playground
 docker run -d -p 8080:8080 hyperledger/composer-playground

Once you have configure your business network you can export it in a BNA (business network archive file).

 

The Business Network

Permissioned blockchain technology applications built for the enterprise and commercial applications need an abstraction layer. This is provided by Fabric Composer; a toolset and application framework that enables you to quickly model and deploy applications to Fabric infrastructure. It is a framework that enables you to reason about the Participants, the Assets, and the Transaction logic that drive state changes on your distributed ledger. This business logic and processes are what will drive the distributed state changes to the peers on your network.

Hyperledger Fabric Composer

Fabric Composer is an open-source project and part of the Hyperledger Foundation.

First, ssh into the same VM you setup.

ssh -i ./yourkeyname.pem ubuntu@yoururlname

Installing Fabric Composer Dev Tools

You should have the majority of these tools installed in your configured VM but this script will make sure everything is correct versions and you haven’t missed anything.

curl -O https://hyperledger.github.io/composer/prereqs-ubuntu.sh

chmod u+x prereqs-ubuntu.sh
./prereqs-ubuntu.sh
  1. To install composer-cli run the following command:
    npm install -g composer-cli
    

    The composer-cli contains all the command line operations for developing business networks.

  2. To install generator-hyperledger-composer run the following command:
    npm install -g generator-hyperledger-composer
    

    The generator-hyperledger-composer is a Yeoman plugin that creates bespoke applications for your business network.

  3. To install composer-rest-server run the following command:
    npm install -g composer-rest-server
    

    The composer-rest-server uses the Hyperledger Composer LoopBack Connector to connect to a business network, extract the models and then present a page containing the REST APIs that have been generated for the model.

  4. To install Yeoman run the following command:
    npm install -g yo
    

    Yeoman is a tool for generating applications. When combined with the generator-hyperledger-composer component, it can interpret business networks and generate applications based on them.

If you use VSCode, install the Hyperledger Composer VSCode plugin from the VSCode marketplace. There is also a plugin for Atom as well.

Make sure you have the V1 images, if you have any old ones use:

sudo docker rmi <image> --force
sudo docker container prune

Fabric Tools 

mkdir ~/fabric-tools && cd ~/fabric-tools

curl -O https://raw.githubusercontent.com/hyperledger/composer-tools/master/packages/fabric-dev-servers/fabric-dev-servers.zip
sudo apt install unzip
unzip fabric-dev-servers.zip
export FABRIC_VERSION=hlfv1

To download Hyperledger-Fabric use the script below:

cd ~/fabric-tools
./downloadFabric.sh
sudo docker images
hyperledger/fabric-ca x86_64-1.0.1 5f30bda5f7ee 2 weeks ago 238MB
hyperledger/fabric-couchdb x86_64-1.0.1 dd645e1e92c7 2 weeks ago 1.48GB
hyperledger/fabric-orderer x86_64-1.0.1 bbf2708c9487 2 weeks ago 179MB
hyperledger/fabric-peer x86_64-1.0.1 abb05def5cfb 2 weeks ago 182MB
hyperledger/fabric-ccenv x86_64-1.0.1 7e2019cf8174 2 weeks ago 1.29GB

You can start Hyperledger Fabric using this script:

./startFabric.sh

if you run:

sudo docker ps

You should see your network is up and running

Create and Connect your Hyperledger Composer Profile

Hyperledger Fabric is distinguished as a platform for permissioned networks, where all participants have known identities.

UPDATE: ID Cards

The below line should be a huge ah-hah moment.

**********An ID Card contains an Identity for a single Participant within a deployed business network. ************

You have defined a Participant in your business network (modeled, but also actually created a record of one) given the participant an ID (id, name email) and now; the above. The ID Card contains an Identity for that single Participant within the deployed business network.

It is like your auth method. You create the participant on the network and then you can go and create an ID that lets you sign as as that participant. Then create another participant, maybe same type, different type; then create another ID for that one.

*** Command Line – Create Profile ***

Issue from the fabric-tools directory ./createComposerProfile.sh

This script will create an PeerAmin Profile for you.

Connection profiles are a bit confusing and can be frustrating to setup, but, this is an integral part to being able to build and deploy your business network.

There are two folders on your machine:

cd ~/.composer-credentials

and

cd ~/.composer-connection-profiles

When you run Composer locally using Docker containers the Profiles you create will be stored there.

You can find you and PeerAdmin Profile pub, priv keys in the composer-credentials directory.

You then have to import you Composer Profile using this command:

$ composer identity import -p hlfv1 -u PeerAdmin -k
/c/Users/domst/.composer-credentials/114aab0e76bf0c78308f89efc4b8c9423e31568da0c340ca187a9b17aa9a4457-priv
 -c /c/Users/domst/.composer-credentials/114aab0e76bf0c78308f89efc4b8c9423e31568da0c340ca187a9b17aa9a4457-pub

OR

composer identity import -p hlfv1 -u PeerAdmin -c ${HOME}/.composer-credentials/114aab0e76bf0c78308f89efc4b8c9423e31568da0c340ca187a9b17aa9a4457-pub -k ${HOME}/.composer-credentials/114aab0e76bf0c78308f89efc4b8c9423e31568da0c340ca187a9b17aa9a4457-priv

You should get a Command Successful Message.

You may run into a problem command if your setup is still sudoed out, so you will need to check and see using

ls -la /home/ubuntu/.composer-credentials

Then if it is run

sudo chown -R ubuntu /home/ubuntu/.composer-credentials

Network Teardown

Also, here are some more scripts more to stop and tear down the infrastructure layer.

./stopFabric.sh

At this point you can go should be ready to get dialed in and ready to model out and wire up a business network. Grab some coffee, a nice glass of water, new piece of gum; you’re just about to get going. This next part we are going to connect a Sample Business Network to your Hyperledger Fabric V1 Blockchain.

To start over do this

./teardownFabric.sh

Or continue On… to connect a Sample Business Network to your Hyperledger Fabric V1 Blockchain.

Building Your Business Network

This section isn’t mandatory but if you want to use the playground editor this is some background on how to to access it in the browser Or you can skip this and use vim.

Make sure fabric composer is running, your security groups have inbounds and outbounds open and go to your amazon web services url:

then go to the extension for composer editor.

http://yourURL.compute.amazonaws.com:8080/editor

Model your Business Network using the Hyperledger Composer Playground. A Hyperledger Composer Business Network Definition is composed of a set of model files and a set of scripts.  This can be run in the browser or locally using a docker container.

Modeling a Business Network consist of :

  • Participants – Members of the Business Network
  • Assets –
  • Transactions – State change mechanism of the Network

You also are able to use:

  • Concepts
  • enum
  • abstract

Lastly, the Business Network can define:

  • Events – Defined indicators that can be subscribed to by external systems
  • Access Control – Permissions for state changes

You can use Javascript to define the transactional logic that you would like to use in your applications. We are just going to use a Sample Business Network, this can be edited and redeployed to update the Blockchain.

Clone a sample network using this repo:

git clone https://github.com/hyperledger/composer-sample-networks.git
cd packages

cd basic-sample-network

npm install

You should get something like this:

Creating Business Network Archive

Looking for package.json of Business Network Definition
Input directory: /home/ubuntu/my-network

Found:
Description: The Hello World of Hyperledger Composer samples
Name: my-network
Identifier: my-network@0.1.8

Written Business Network Definition Archive file to
Output file: ./dist/my-network.bna

Command succeeded

 

Deploying Your Business Network To Your Blockchain Infrastructure

Once you have your Sample Business Network you are going to want to create a BNA file. A BNA is the Business Network Archive, it is a file that describes your network configuration and application and can be deployed the the infrastructure you have setup. To deploy your network use:

composer network deploy -a my-network.bna -p hlfv1 -i PeerAdmin -s randomString

TROUBLESHOOTING:

✖ Deploying business network definition. This may take a minute…

Error: Error trying deploy. Error: Error trying install chaincode. Error: Failed to deserialize creator identity, err ParseCertificate failed asn1: structure error: tags don’t match (2 vs {class:0 tag:6 length:7 isCompound:false}) {optional:false explicit:false application:false defaultValue:<nil> tag:<nil> stringType:0 timeType:0 set:false omitEmpty:false} @2
Command failed

Stack Overflow Answer

Setting up our REST Server

Hyperledger Fabric v1.0 provides basic API using Protocol Buffers over gRPC for applications to interact with the blockchain network. Composer enables you to create REST server and communicate with the Blockchain network using JSON. This part is important and you should have an understanding of it before starting on modeling out your business network / application. Composer enables you to create a REST server that is dynamically generated based on the business network participants and asset you design. You can configure your network and launch a REST Api that can be called from other applications.

composer-rest-server

Wiring It All Up

Once your business Network is deployed to your infrastructure you should be able to verify it using the top right, your connection profile is connected. You are now ready to send transactions to the blockchain directly from the composer interface or by calling your REST server from a client.

If you are running into any trouble feel free to reach out at dominic@dapps.ai

Versions:

https://gateway.ipfs.io/ipfs/QmXMaNJRGstyib8iAZCZ5HxShorCxCDFDzeG2Hx73hTYcp

5.26 – using v1.0

https://gateway.ipfs.io/ipfs/QmWtaoMGA8SVc7kdjUnRP5hS1KsX51TEYH57VNTPJWQPFh

5.27 – using v1.0 alpha2 docker images and added in fabric composer (current)

https://gateway.ipfs.io/ipfs/Qme6FT3HQzUsY8z69P6KCutaUogmc4BBxCSPJDt3czaM6M