Hyperledger Fabric (HLF) is a blockchain framework hosted by The Linux Foundation. This post is a technical walkthrough for those wanting to quickly get a running setup with Hyperledger for testing its features.
Getting started with HLF is not easy as there are first a lot of concepts to understand (blockchain, ledger, smart contract, channels, peers, consensus, etc.) directly related to the use of a blockchain solution and then once these concepts are understood, the way these translate into HLF.
HLF provides a nice getting started environment based on docker for experimenting with its features. Their sample environment allows for easy and hassle-free setup.
Without getting into too much detail, a few base elements are needed to get started:
- the different binaries
- a config file for generating the required cryptographic material called crypto-config.yaml (certificates, etc)
- a few images for each of the various components (peers, orderers, etc)
- a docker-compose file to properly start/manage the different docker containers
- a channel configuration file called configtx.yaml (defines the different channels, organizations, etc)
One could follow the sample documentation of HLF to get a working setup. However, we are open sourcing a config helper for HLF that generates all the various config files as well as a few scripts to ease the deployment of a test environment: https://github.com/kudelskisecurity/hlf-cfg-gen.
hlf-cfg-gen is composed of a Python3 script using jinja2 and a few configuration/script templates which, when run will generate everything you need to get a working setup. It also allows to easily control different elements related to your blockchain (number of organization, number of user, etc).
Here’s a walkthrough on getting it running. Start by making sure you have a recent version of the following tools installed:
- docker
- docker-compose
Then clone the tool directly on your host:
$ cd /tmp/; git clone https://github.com/kudelskisecurity/hlf-cfg-gen $ cd hlf-cfg-gen
One then needs to retrieve the different binaries used by HLF to generate the necessary elements. These are provided directly on Github on their repositories. For example to get the HLF bootstrap script for version 1.1 of Hyperledger Fabric, one would issue the following commands.
$ wget https://raw.githubusercontent.com/hyperledger/fabric/release-1.1/scripts/bootstrap.sh $ chmod +x bootstrap.sh $ ./bootstrap.sh
This downloads the docker images (and tags them properly) for running the different HLF containers. Here’s an overview of the downloaded images:
hyperledger/fabric-ca latest hyperledger/fabric-ca x86_64-1.1.0 hyperledger/fabric-tools latest hyperledger/fabric-tools x86_64-1.1.0 hyperledger/fabric-orderer latest hyperledger/fabric-orderer x86_64-1.1.0 hyperledger/fabric-peer latest hyperledger/fabric-peer x86_64-1.1.0 hyperledger/fabric-javaenv latest hyperledger/fabric-javaenv x86_64-1.1.0 hyperledger/fabric-ccenv latest hyperledger/fabric-ccenv x86_64-1.1.0 hyperledger/fabric-zookeeper latest hyperledger/fabric-zookeeper x86_64-0.4.6 hyperledger/fabric-kafka latest hyperledger/fabric-kafka x86_64-0.4.6 hyperledger/fabric-couchdb latest hyperledger/fabric-couchdb x86_64-0.4.6
The bootstrap script also downloads the binaries placing them in the bin directory. To ease the process, the binaries path needs to be added to the PATH, for example with:
$ export PATH="$(pwd)/bin/:${PATH}"
Then the different configuration files and scripts can be generated using hlf-cfg-gen with the following:
# install the required modules with pip3 $ sudo apt install python3-pip virtualenv $ virtualenv -p python3 env $ source env/bin/activate $ pip install -r requirements.txt # generate the files with hlf-gen.py $ ./hlf-gen.py gen
Of course hlf-gen.py allows customization of the various settings of your blockchain setup:
- Number of organizations
- Number of peers
- Number of users
- Specify the different ports for the containers
- and more …
See the usage to see all available options:
$ ./hlf-gen.py --help
All needed files are to be found in the configs directory. Here’s a small description of what is being generated:
- channels.sh – This script contains everything to initiate the different channels on HLF. One per organization and a common channel shared by all organizations.
- configtx.yaml – Config file that allows to generate the base block for starting the blockchain on each channel.
- crypto-config.yaml – Config file used to generate the cryptographic material.
- docker-compose.yml – The docker compose config file used to spin all containers.
- generate.sh – Script that uses the two config files (configtx.yaml and crypto-config.yaml) to generate the channel configuration and the anchor peer transactions.
- start.sh – Little wrapper script around docker-compose to bootstrap the network.
- stop.sh – Little wrapper script around docker-compose to stop the network.
The next step is then to get the blockchain up and running. Start by generating all the configs and cryptographic material:
$ cd configs $ ./generate.sh
Then start it:
$ ./start.sh
And finally initiate the channels:
$ ./channels.sh
That’s it. A test network of Hyperledger Fabric is up and running. Any command can be run on the platform by interacting with the peers. For example, one could list the different channels available:
$ docker exec -e CORE_PEER_LOCALMSPID=Org1MSP -e CORE_PEER_MSPCONFIGPATH=/etc/hyperledger/msp/users/[email protected]/msp peer0.org1.example.com peer channel list Channels peers has joined: org1chan commonchannel
For more commands with peer, see the offical documentation: https://hyperledger-fabric.readthedocs.io/en/v1.1.0-alpha/peer-commands.html.
The above walkthrough was tested on a clean Ubuntu 18.04 with HLF 1.1.
For more, see the tool on github under https://github.com/kudelskisecurity/hlf-cfg-gen.
Some references:
Kudelski Security Research 