Setting Up the External Chaincode Builder and Launcher in Hyperledger Fabric 2.0

A Step by Step Guide

Photo by Launchpresso on Unsplash

Indroduction

Hyperledger Fabric version 2.0 was released on January 29th, 2020. The major release delivers numerous of new features. One of these features is the External Chaincode Launcher. In Hyperledger Fabric version 1.x, building and launching chaincode was part of the peer implementation and therefore could not be customized without changing the source code. Prior to Hyplerdeger Fabric 2.0, the peer node used a hardcoded language specific logic (e.g. Golang), which generated an executable Docker container image from the chaincode source.

This approach limited chaincode implementations to a handful of languages, required Docker to be part of the deployment environment, and prevented running chaincode as a long running server process. [1]

The recently introduced external chaincode builders and launchers address the limitations above. Beginning with Hyperledger Fabric 2.0, operators are enabled to extend the peer with scripts (buildpacks) that can discover, build and launch chaincode.

The scheme below visualizes the difference between the internal chaincode builder and launcher in Hyperledger Fabric version 1.x and the external chaincode builder and launcher available since Hyperleder Fabric version 2.0 at a high level.

Internal vs. external chaincode builder and launcher

This article provides a step by step guide to set up your first external builder for golang (Go) chaincode. To follow up this example, it is highly recommended to read and follow the Building Your First Network tutorial as well as the section about the External Builders and Launchers in advance.

Overview

In total, there are 8 steps to follow in order to complete this step by step guide. The first two steps are about getting started. Steps 3 to 6 implement the external chaincode builder and launcher, which is the most crucial part. Finally, the last two steps will start a blockchain network and run the chaincode.

If you don’t want to examine steps 3, 4, (5) and 6 manually, you can clone the example from my Github repo, which is a fork of hyperledger/fabric-samples. All needed data is located in fabric-samples/test-network in my repo. In case of step 5, you can either use the Docker image from my Dockerhub or build your own Docker image.

1. Install Prerequisites
2. Install Samples, Binaries and Docker Images
3. Create Buildpack
4. Edit core.yaml File
5. Build new Peer Docker Container Image
6. Config docker-compose File
7. Start Network & Create Channel
8. Deploy Chaincode with the External Builder

The following graphic provides an overview of steps 3 to 6 and shows the dependencies of each step.

Setting up the external chaincode builder and launcher

Step 1: Install Prerequisites

If you haven’t done so far, go the the Install Prerequisites section in the official docs and check whether you already have all prerequisites installed. If not, just follow the docs.

Step 2: Install Samples, Binaries and Docker Images

Now it’s time to Install Samples, Binaries and Docker Images. Please, just follow the docs. The official documentation of Hyperledger Fabric 2.0 will guide you through the installation process and provide you with helpful scripts.

Step 3: Create Buildpack

Next, you need to create a buildpack, which is basically a collection of scripts that compile your chaincode for launch. In Hyperledger Fabric 2.0, an external builder and launcher consists of four programs or scripts as follows [1]:

bin/detect: Determine whether or not this buildpack should be used to build the chaincode package and launch it.

bin/build: Transform the chaincode package into executable chaincode.

bin/release (optional): Provide metadata to the peer about the chaincode.

bin/run (optional): Run the chaincode.

I based my buildpacks on the docs and the Hypledger Fabric 2.0 integration tests. Thus, most of the credits go to the developers of HL Fabric. In order to use the buildpacks provided in the docs, you have to change the shebang from #!/bin/bash to#!/bin/sh because Fabric 2.0 started using Apline-based docker images, which don’t include a bash shell. Store the scripts in a directory, here called external-builder/bin. Alternatively, you can use the buildback from my repo.

Open a terminal in the external-builder/bin folder and run the following command:

chmod -R 777 ./

The command makes the file readable, writable and executable by everyone, which is appropriate for testing purposes. To implement the external builder, you need to edit the core.yaml file (Step 4), create a new Docker image for the peer container (Step 5), and config the docker-compose-test-net.yaml file (Step 6).

Step 4: Edit core.yaml File

To ensure that the peer picks up the external builder, you have to modify the peer’s core.yaml file to include the external builder that you have created in the step above. A sample of the peer core.yamlfile is located under fabric-samples/config which you can use as a starting point. Go to the the section of the externalBuilders and edit the path to the parent of the bin directory containing the builder scripts. Add a name and set env variables you want to pass to your externalBuilders to the environmentWhiltelist.

externalBuilders:
    - path: /path/to-your/external-builder
      name: my-golang-builder
      environmentWhitelist:
        - GOPROXY
        - GONOPROXY
        - GOSUMDB
        - GONOSUMDB
        - GOCACHE
        - GOPATH
        - GOROOT
        - HOME
        - XDG_CACHE_HOME

If the external builder fails, the peer will fall back to the internal build process of the chaincode and start the chaincode in a Docker container.

Step 5: Build new Peer Docker Container Image

If you take a look at the scripts of the external builder you will see that the scripts contain the commands go build and jq, which are not included natively in the hyperledger/fabric-peer Docker image. Thus, we have to modify the dockerfile and then build a new image, that we can use later.

You can clone the dockerfile from the hyperledger/fabric github repo. You have to replace line 8 and 9 with the following:

FROM golang:${GO_VER}-alpine${ALPINE_VER} as peer-base
RUN apk add — no-cache tzdata jq

After you have modified the dockerfile, build a new image and tag it to the name you will use in the docker-compose file. The new image includes jq , and is based on the golang apline image instead of just the regular alpine image. I also provide the modified dockerfile in my github repo. However, you still need to build the image by your own.

Alternatively, you can pull the Docker image I created as follows:

docker pull udosson/udosson:hyperledger-fabric-peer-golang-jq

Step 6: Config docker-compose file

In this step, we will configure the docker-compose file to include all the steps we have accomplished so far.

The test-network consists of one orderer and two peer nodes belonging to two different organizations, which you need to configure. More details about the test-network can be found in Using the Fabric test network section in the docs.

To configure the peer nodes you need to modify the docker-compose-test-net.yaml which is located at test-network/docker. For each peer, paste the tag of newly created images in step 5, add the external builder to the peer and override the core.yaml file.

Change the image for peer0.org1.example.com:

peer0.org1.example.com:
     container_name: peer0.org1.example.com
     image: tag-of-the-golang-alpine-image

Add the external builder and the core.yaml of peer0.org1.example.com to the volumes. The core.yaml file of the peer will then be replaced by your modified file. Attention! The path to the external builder inside the peer container must be the as same as the path to the external builder in the core.yaml file.

volumes:
    - …
    - peer0.org1.example.com:/var/hyperledger/production
    - ./path-to-external-builder:/etc/hyperledger/external-builder
    - ./path-to-edited-core.yaml/:/etc/hyperledger/fabric

Modify peer0.org2.example.com in the docker-compose-test-net.yaml accordingly.

Step 7: Start Network & Create Channel

Next, you can can start the test-network and create a channel. Run the following command from the fabric-samples/test-network directory. The command starts the network automatically, creates a channel and makes the peers join the channel called mychannel.

./network.sh up createChannel

Step 8: Deploy Chaincode with the External Builder

Once the network is up, you can start the chaincode with the external builder and interact with the network. To start the chaincode, you can use the following command from within the fabric-samples/test-networkdirectory. The command will install the fabcar chaincode to the peers and deploy the chaincode to the channel mychannel.

./network.sh deployCC

You can check, if you have successfully built and launched your first chaincode by the external builder by the command docker ps. In the screenshot below, you can see the query command from /network.sh deployCC subscript and the results of the commanddocker ps. After the chaincode is running, there are still just two peer and one orderer container running.

Feel free to interact with the network as shown in the section Interacting with the network of the docs.

Summary

This step by step guide showed you how to use the new Hyperledger Fabric 2.0 feature “External Builders and Launchers”. The example is based on the fabric-samples github repository and uses the test-network. With the help of the external chaincode feature you can build and launch chaincode with the technology of your choice. Since Hyperledger Fabric 2.0, the requirement to provide access for the peer to a Docker daemon is removed and therefore enables operators to deploy chaincode in a Kubernetes pod, for example.

Finally, I want to thank Brett Logan and Andrew Hurt for their support to get my first external chaincode builder and launcher to run.

If you have any questions, feel free to leave a comment below

Robin Klemens

[1] https://hyperledger-fabric.readthedocs.io/en/release-2.0/cc_launcher.html