How to setup Hyperledger Fabric and Composer
- Hyperledger Fabric is a private blockchain network that provides a foundation for transactional enterprise application
- Hyperledger Composer is a framework to accelerate the development of applications built on top of Hyperledger Fabric
Fabric and Composer are open source collaborative blockchain framework projects that is hosted by The Linux Foundation. The Fabric blockchain framework is built from the ground-up for enterprise level application, it is a permissioned network, meaning read/write access to the shared ledger and participation in the peer-to-peer network is restricted to invited and validated members, such restriction makes way for advantages like scalability and confidential transactions that are a fundamental requirements for most enterprise applications.
This is a major differentiation from other known blockchain implementations like Bitcoin and Ethereum that are public and fully decentralized, paving a way for anyone to join, participate and maintain the peer-to-peer network. Another differentiation is that the Fabric blockchain does not have a built-in native token/coin like the native cryptocurrency, bitcoin and ether that are built-in to Bitcoin and Ethereum blockchain respectively.
The diagram below shows the relationship between the Fabric network and the Composer framework. The Composer framework runs in its own isolated runtime, and it is connected to the Fabric network through the means of connection profiles that allows deployment of defined Business Network Definition (BND) archive files (.bna files) that is generated by the Composer framework.
BND comprises and captures all the necessary components (files, rules and logics) that makes up a business network solution. Here are some of the details that makes up a BND.
- Model files (Assets, Participants, Transactions, Events): Data model is written in an expressive JSON serializable modeling language. which are namespaced and are validated by the runtime that defines relationships and validation rules.
- Transactions processor (Business logic and requirements): It uses an annotated native JavaScript (ES5) code that has a set of built-in registry JavaScript API. The code is executed on the network by the runtime.
- Access control list: Enforces rules by the runtime for sharing and permitting access to resources.
There are couple ways to go about setting up the Fabric Network. Please note, hyperledger project is actively being developed by the foundation, therefore the steps below may have changed and improved since the last time I had installed and setup my development environment.
- (Recommended) Setting up with the intention of using Composer for the basis for application development.
- Setting up natively with the intention of using Golang for chaincode (aka smart contract) development.
(Recommended) Setup of Hyperledger Fabric Network:
Prerequisite (Setting up local development environment)
- (Optional but highly recommended) Install virtual environment: https://realpython.com/blog/python/python-virtual-environments-a-primer/
- Patiently Install (Python 2.7.x+, Git 2.9.x+, Docker Engine -v17.03+, Docker Compose -v1.8+, Node.js -v6.x (Node v7+ is not supported), and Xcode if on Mac). Set recommended FABRIC_VERSION=hlfv1(v1.0) as an environment variable. Here are some instructions to get started, please follow the links for more installation steps.
# install git
https://www.atlassian.com/git/tutorials/install-git
# install node version 6
https://medium.com/@katopz/how-to-install-specific-nodejs-version-c6e1cec8aa11
~$ brew update
~$ brew install node@6
~$ brew unlink node
~$ brew link node@6
~$ node --version
~$ npm --version
# install docker
https://docs.docker.com/engine/installation/
# set environment variables for Fabric v1.0
~$ export FABRIC_VERSION=hlfv1
~$ export FABRIC_START_TIMEOUT=15 - Kill all previously running docker container and remove all images
~$ docker kill $(docker ps -q)
~$ docker rm $(docker ps -aq)
~$ docker rmi $(docker images dev-* -q) - Create a directory and download the zip containing the composer scripted tools. Once unzipped, note the scripts for downloading, starting and stopping the Fabric Network in the/fabric-tool folder.
~$ mkdir ~/fabric-tools && cd ~/fabric-tools
~$ curl -O https://raw.githubusercontent.com/hyperledger/composer-tools/master/packages/fabric-dev-servers/fabric-dev-servers.zip
~$ unzip fabric-dev-servers.zip - Download and start the Fabric Network and create a profile to connect Composer.
~$ cd ~/fabric-tools
~$ ./downloadFabric.sh
~$ ./startFabric.sh
~$ ./createComposerProfile.sh
# check the running docker container. There should be at least a peer node, ca node, orderer node and a couchdb container.
~$ docker ps - The Fabric Network should all be setup at this point. At the end of your development, you may choose to stop and teardown the Fabric Network.
~$ cd ~/fabric-tools
~$ ./stopFabric.sh
~$ ./teardownFabric.sh - Congratulations!! The Fabric Network should all be set up. Next step is to complete the setup of Hyperledger Composer development tools. Issue the following commands to get Hyperledger Composer installed locally in your development environment.
~$ npm install -g composer-cli
~$ npm install -g generator-hyperledger-composer
~$ npm install -g composer-rest-server
~$ npm install -g yo
(Optional) Natively Setting up Hyperledger Fabric Network:
Prerequisite (Setting up local development environment)
- (Optional but highly recommended) Install virtual environment: https://realpython.com/blog/python/python-virtual-environments-a-primer/
- Patiently Install (Python 2.7.x+, Git 2.9.x+, Golang -1.8.0+, Docker Engine -v17.03+, Docker Compose -v1.8+, Node.js -v6.x (Node v7+ is not supported), and Xcode if on Mac). Setup environment variables for Golang. Here are some instructions to get started, please follow the links for more installation steps.
# install golang and set environment variables
https://golang.org/doc/install
~$ export GOPATH=$HOME/go
~$ export PATH=$PATH:$GOPATH/bin
# echo $GOPATH should print $HOME/go (e.g. /Users/ejiro/go)
~$ echo $GOPATH
# install git
https://www.atlassian.com/git/tutorials/install-git
# install node version 6
https://medium.com/@katopz/how-to-install-specific-nodejs-version-c6e1cec8aa11
~$ brew update
~$ brew install node@6
~$ brew unlink node
~$ brew link node@6
~$ node --version
~$ npm --version
# install docker
https://docs.docker.com/engine/installation/
# set environment variables for Fabric v1.0
~$ export FABRIC_VERSION=hlfv1
~$ export FABRIC_START_TIMEOUT=15 - Install Hyperledger Fabric core implementation (v1.0): https://github.com/hyperledger/fabric/tree/v1.0.0-preview
~$ mkdir -p $GOPATH/src/github.com/hyperledger
~$ cd $GOPATH/src/github.com/hyperledger
~$ git clone https://gerrit.hyperledger.org/r/fabric
~$ cd fabric
# should be on the * release branch
~$ git branch - Create workspace directory. Essentially, this workspace will house all your projects (both sample, demo or production projects). For the basis of this setup, I will be cloning and using the marbles demo app created by IBM.
~$ mkdir ~/workspace && cd ~/workspace - Download the marbles demo from the IBM github repository within workspace directory. Please make sure to checkout latest branch (I used v3.0 when I tested out the sample, IBM is actively deprecating and releasing new versions). if you can’t checkout v3.0 using the git command, try downloading it manually or perhaps follow the instructions for the active version. https://github.com/IBM-Blockchain/marbles
~$ git clone https://github.com/IBM-Blockchain/marbles.git --depth 1
~$ cd marbles
~$ git checkout v3.0 - Download the docker images required for setting up and running the Fabric Network locally.
~$ cd marbles/scripts
~$ chmod +x download-dockerimages.sh
~$ sudo ./download-dockerimages.sh - Setup Fabric Node SDK. This script will download the Fabric Client Node.js SDK which subsequently sets up an environment for interacting with the Fabric Network.
~$ sudo ./setup_sdk.sh - Start the Fabric Network. The*.yamlfile contains all the configured certificate authorities (CA) containers, member nodes as peers (endorsers & committers) and ordering service nodes (orderers).
~$ cd ./fabric-sdk-node/test/fixtures
~$ sudo docker-compose -f docker-compose-marblesv3.yaml up -d
~$ docker ps (to see running containers) - Setup the Fabric Network by creating a channel and joining peers to the channel. You may recall that Hyperledger is a permissioned blockchain, therefore the Fabric channel helps facilitate private and confidential transactions within each peers that joined the channel. Issue the following node commands from within the /script directory.
~$ cd ../fabric-sdk-node/
~$ node test/integration/e2e/create-channel.js
~$ node test/integration/e2e/join-channel.js - Optionally, you may choose to view the logs of the docker containers for each peers and orderer.
~$ sudo docker logs -f peer0
# control + c will exit the process
~$ sudo docker logs -f orderer0 - Congratulations!! The Fabric Network should all be setup. At this point, you may choose to test out the demo by Installing and Instantiating the Marbles chaincode (smart contract) then Host and Run the demo app
For more detailed information and troubleshooting steps, please visit: https://github.com/IBM-Blockchain/marbles/blob/v3.0/README.md
Next steps:
To fully take advantage of such a setup, one needs to create a decentralized application utilizing the Fabric blockchain network as its underlying distributed database. Check out our next tutorial on How to create a decentralized application running on Hyperledger Fabric Network.
Official Resources:
Other Resources:
References:
