Introduction

In the blockchain world there are basically two types of blockchain - the public and the private blockchain. Hyperledger Fabric (HLF) can be assigned to the private blockchain world. In this article I would like to explain how you get started with this technology.

In a permissionless (public) blockchain, on the one hand, virtually anyone can participate and every participant is anonymous. On the other hand, permissioned (private) blockchains operate amongst a set of known, identified and often verified participants who act under a governance model that yields a certain degree of trust.

According to the official documentation HLF can be defined as follows:

Hyperledger Fabric is an open source enterprise-grade permissioned distributed ledger technology (DLT) platform, designed for use in enterprise contexts, that delivers some key differentiating capabilities over other popular distributed ledger or blockchain platforms.

If you are interested in building a private, permissioned blockchain with HLF, then this newsletter is right for you. In this and in the upcoming articles I will give my subscribers a guide to explore the newest Fabric Long-Term-Support (LTS) version 2.2.x.

This article is divided into two parts:

• Part one - the set-up; As a first step we are going to set-up our own development environment.
• Part two - a first try of the new test network, as a teaser - more will come.

Prerequisites

In my experience, the easiest way to get started is with any kind of virtualization. You can use some virtualization software on your computer like VirtualBox. In this case, it does not matter if you use a Windows, Mac or Linux Operating System (OS) or you use one of the public Infrastructure as a Service (IaaS) providers. In this case, I use a DigitalOcean droplet with 1 CPU, 2 GB RAM and the corresponding 50 GB SSD storage.

As a base image I take an Ubuntu Focal 20.04 (LTS) image. This image includes a lot of useful tools and we can get started basically without any problems regarding the system requirements.

When the preparatory work is completed, we can start with the set-up.

Set-up

The set-up process can be summarized as follows:

Installation - Helper Tools

As a first step, we install two useful helper tools. The first tool I would like to recommend is tree. Tree is a tiny, cross-platform command-line program used to recursively list or display the content of a directory in a tree-like format. It outputs the directory paths and files in each sub-directory and a summary of a total number of sub-directories and files. This is useful if you want to inspect some folder content especially the content of the Membership Service Providers (MSP) folders.

The second tool I would like to propose is jq. jq is a lightweight and flexible command-line JSON processor. If you are a command line addict, you will like the official description. jq is like sed for JSON data. You can use it to slice, filter, map, and transform structured data with the same ease as sed, awk, grep and friends let you play with text. In our context jq can be used to pretty print several Fabric outputs such as chaincode (CC) response or channel configuration.

To finish this step the following commands are required:

# update the OS
apt update && apt upgrade

# install some useful helpers
apt install tree jq

# it's always good the use the right time
# so set-up the correct timezone
timedatectl set-timezone Europe/Vienna

# check the time
date

Now we are ready to install Docker and Docker-Compose.

Installation - Docker, Docker-Compose

HLF is Docker based and that is the reason why we have to install Docker and Docker-Compose in our development environment. If you are not familiar with Docker and Docker-Compose, please take a look at the official Docker or Docker-Compose documentation or consult several public sources regarding this topic. Even in the case you know Docker and its surrounding environment it is worth refreshing some Docker knowledge because we will make heavy usage especially with the Docker command-line interface (CLI). It is also good to understand the concepts behind Docker and how you can use that kind of virtualization technology for your own purpose.

According to the official Docker documentation the following steps are required to install docker on your target OS. Please, keep in mind that a Docker version 17.06.2-ce or higher is required.

Please, note that all commands are executed with the sudo command. The sudo command allows you to run programs as another user, by default the root user.

# setup Docker’s repository
sudo apt-get install \
  apt-transport-https \
  ca-certificates \
  curl \
  gnupg-agent \
  software-properties-common

# add Docker's official GPG key
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -

# add the stable Docker repository
sudo add-apt-repository \
  "deb [arch=amd64] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) \
  stable"

# as a last step install Docker
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io

# check the result, the docker version
sudo docker --version

After finishing the process to install Docker we are ready to install Docker-Compose. Please, keep in mind as well that a Docker-Compose version 1.14.0 or higher is required.

# install docker-compose
sudo curl -L "https://github.com/docker/compose/releases/download/1.26.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

# apply executable permissions to the binary
sudo chmod +x /usr/local/bin/docker-compose

# check the result, the docker-compose version
sudo docker-compose --version

At this point, we are ready with Docker related preparations. Let us switch over to the next step.

Installation - Golang, Node.js

To complete our development environment we need two more pieces. The first part is Golang. Golang is used for CC development and if you want to develop your own CC then Golang could be a good choice for that - although Fabric supports different programming languages to develop CC. At the time of writing you can write and install CC in Go, Node.js and Java.

The CC typically handles the business logic in the network agreed to by the members of the network. So, it is similar to a so-called “smart contract” as you can find in other blockchain systems.

In our scenario we are going to install Golang for CC development and Node.js for the client application development. The so-called client application is used to interact with the Fabric network and can be used as a Representational State Transfer (REST) Application Programming Interface (API).

At this point, I would like to open your mind and deliver a larger picture of a permissioned blockchain system. In the graphic below you can see three boxes. The first box represents the Fabric network itself. The second box shows a Fabric client application. The third and last box is a frontend application which is not part of the Fabric network and mostly developed with a JavaScript Framework like Angular or Vue.js.

All these boxes have different roles in the field of information technology (IT). For instance, we can assign the role of an operator or administrator to the Fabric network. A CC developer is dedicated to the Fabric Client. And, for the frontend application Fabric offers a wide range of SDKs to compose client applications. This third group of IT professionals does not necessarily have to have in-depth knowledge of Fabric. They only have to interact with a kind of layer, like a database for example, and they can work with different standard languages. Currently, some are officially supported and some are not.

In this article we are focusing on the first box, the Fabric network, and how we can take the first steps. The reason for mentioning that in the installation section is to point out how the single pieces belong to each other. Fabric itself has been specifically designed to have a modular architecture. That means that you can implement your network in different ways to meet your business needs. For CC development you can use standard programming languages, as mentioned before.

Now we come back to the topic and we install Golang and Node.js. We start with Golang. According to the Fabric 2.2 documentation Go 1.14.x is required. Use the following commands to download and extract Golang 1.14.9 as the current required version.

# download and extract golang
# latest version 04.10.20 1.14.9
sudo wget -c https://dl.google.com/go/go1.14.9.linux-amd64.tar.gz -O - | tar -xz -C /usr/local

After having successfully downloaded and extracted the Golang package modify the ~/.profile file on your development system. This file is used to configure the users environment in the development environment. The instructions in the file usually set some shell variables, such as PATH, USER, and HOSTNAME. In our case we have to execute two things:

1. Expand the PATH variable by the path to the fabric-sample/bin folder which we are going to install in the last step of the installation process.
2. Set the GOPATH variable to the root of our fabric-samples directory, $HOME/fabric.

Basically the $GOPATH/bin directory is where Go places binaries that go install compiles. Our operating system uses the $PATH environment variable to find binary applications that can execute without a full path. It is recommended to add this directory to our global $PATH variable.

To edit this file you can use VI or VIM. On Unix-like operating systems vim, which stands for “Vi Improved”, is a text editor. It can be used for editing any kind of text and is especially useful in our scenarios. If you are unfamiliar with VIM it is also worth spending some time and discovering how you can use VIM, because VIM could be very efficient and helpful for your work.

After modifying the ~/.profile file we have to reload it. We can do that with the source command. Source is a shell built-in command which is used to read and execute the content of a file (generally a set of commands) passed as an argument in the current shell script.

The command after taking the content of the specified files passes it to a so-called Tool Command Language (TCL) “tickle” interpreter as a text script which then gets executed. You can imagine TCL is a high-level, general-purpose, interpreted, and dynamic programming language. It was designed with the goal of being very simple but powerful and you can find this tool on many OS.

# open the file and add the go binary to your path
vi $HOME/.profile
export PATH="$PATH:/usr/local/go/bin:/root/fabric/fabric-samples/bin"

# point the GOPATH env var to the base fabric workspace folder
export GOPATH=$HOME/fabric

# exit and save the file with the following key sequence
ESC : wq

# reload the profile
source $HOME/.profile

Finally, we can check our Golang installation with the command go version. Optionally, we can check the current state of environment variables with the command printenv in combination with a piped grep command. The man page describes the command as follows:

Print the values of the specified environment VARIABLE(s). If no VARIABLE is specified, print name and value pairs for them all.

We can use this command to inspect environment variables in different ways. In Fabric we can use a bright range of several environment variables to express or change our configuration.

# check the go version
go version

# check the vars
printenv | grep PATH

Summarized command sequence

# download and extract golang
# latest version 04.10.20 1.14.9
sudo wget -c https://dl.google.com/go/go1.14.9.linux-amd64.tar.gz -O - | tar -xz -C /usr/local

# open the file and add the go binary to your path
vi $HOME/.profile
export PATH="$PATH:/usr/local/go/bin:/root/fabric/fabric-samples/bin"

# point the GOPATH env var to the base fabric workspace folder
export GOPATH=$HOME/fabric

# exit and save the file with the following key sequence
ESC : wq

# reload the profile
source $HOME/.profile

# check the go version
go version

# check the vars
printenv | grep PATH

To complete our set-up steps, finally, we have to install Node.js. As I have mentioned before, we can use Node.js for both CC development and client application development. I use Node.js for client application development. We can use the Node.js SDK also for the interaction with fabric-ca. According to the official documentation fabric-ca is a Certificate Authority (CA) for HLF. In other words, with fabric-ca we can register and enroll users - or more precisely - identities which have the right permissions to interact with the Fabric network, as Fabric is a permissioned blockchain system.

In Fabric 2.2 we can use Node.js version 10 or 12. I would like to use version 12 because the version 12 has LTS and is recommended for most use cases.

As a first step we can use the curl command to download the installation script. curl is a command-line utility for transferring data from or to a server designed to work without user interaction. The aim of that script is to install the NodeSource Node.js 12.x repo onto a Debian or Ubuntu system.

Next we have to execute the downloaded script and finally use the apt-get command to install node.js on the machine. As a final step we can check again the version of the node cli interpreter to make sure everything is up and ready.

Summarized command sequence

# download the installation script
curl -sL https://deb.nodesource.com/setup_12.x -o nodesource_setup.sh

# execute the install script
sudo bash nodesource_setup.sh

# install node.js
sudo apt-get install -y nodejs

# check the version
node -v

Now we have reached a state where we can start installing Fabric related components like needed binaries, docker images and a github repository called fabric-samples.

Fabric Binaries, Images and Samples

HLF is based on Docker images. They provide a script to install all needed binaries. Later they will provide a real installer, but for now we have to use the script. One of the changes from Fabric 1.0 to 2.0 is the usage of Alpine-based docker images. Starting with v2.0, HLF Docker images will use Alpine Linux, a security-oriented, lightweight Linux distribution. This means that Docker images are now much smaller, providing faster download and startup times, as well as taking up less disk space on host systems. Alpine Linux is designed from scratch with security in mind, and the minimalist nature of the Alpine distribution greatly reduces the risk of security vulnerabilities.

As a first step in this last set-up process we can create a new folder called fabric. This folder will be our home or base folder. This is the place where all Fabric related work lives.

The basic command to install the latest version of fabric is:

curl -sSL https://bit.ly/2ysbOFE | bash -s

If you want to install a specific version, e.g. Fabric 1.4.6, then you can pass some version identifier to the script. In detail, you can pass three identifiers to the script <fabric_version> <fabric-ca_version> <thirdparty_version>.

• <fabric_version> stands for the general version of fabric that you want to use
• <fabric-ca_version> means the CA version that you want to use
• <thirdparty_version> represents the CouchDb version that you want to use

curl -sSL http://bit.ly/2ysbOFE | bash -s -- 1.4.6 1.4.6 0.4.18

Summarized command sequence

# create a base folder and switch into
mkdir fabric
cd fabric

# curl -sSL http://bit.ly/2ysbOFE | bash -s -- <fabric_version> <fabric-ca_version> <thirdparty_version>
# curl -sSL http://bit.ly/2ysbOFE | bash -s -- 1.4.6 1.4.6 0.4.18
# curl -sSL https://bit.ly/2ysbOFE | bash -s -- 2.2.1 1.4.9

# latest production ready release, omit all version identifiers.
curl -sSL https://bit.ly/2ysbOFE | bash -s

# check downloaded images
docker images

# check if the binary commands are working (path is set correctly)
peer version

# you should expect an output like this
peer:
 Version: 2.2.1
 Commit SHA: 344fda602
 Go version: go1.14.4
 OS/Arch: linux/amd64
 Chaincode:
  Base Docker Label: org.hyperledger.fabric
  Docker Namespace: hyperledger

If you have followed the installation process until now, congratulations, you should have a usable development environment!

First Try

Now it is time to start the engine. Let us give Fabric a first try and see if we can start a blockchain network. We will discover more about the network in later articles. For the first try, we can use the provided test-network.sh script.

The starting process of the test network is divided in two main steps:

1. Open a terminal on your host machine, bring up the network and create a channel on the ledger.
2. Install a default so-called CC asset-transfer (basic) on our prior composed channel.

Summarized command sequence

# switch to the test-network folder
cd $HOME/fabric/fabric-samples/test-network

# bring up the network
./network.sh up createChannel -c channel1

# install default CC - asset-transfer (basic) chaincode
./network.sh deployCC -c channel1

# show if some containers are running
sudo docker ps
sudo docker-compose -f docker/docker-compose-test-net.yaml ps

# you can expect three running containers
- orderer.example.com 
- peer0.org1.example.com
- peer0.org2.example.com

Now our HLF network is running and we are ready to try the default installed CC asset transfer. This story will be continued in the next article.

Watch the video

As a bonus track you can watch the video as well.

Note

That is it for the first taste of HLF 2.2.x. If you like my articles feel free to subscribe and you will receive all updates to this series as soon as they are available.