The right way to set up the Hyperledger Fabric development environment

Hyperledger Fabric is an exciting technology and is progressing rapidly with the approach of move fast and break things so it can sometimes turn out to be a soul-destroying task to set up the Fabric development environment. Even the official documentation falls short of discussing everything there is in setting up the environment. So, I have written this guide to lay down all the steps you will need to go through to set up the development environment. I will try to keep this guide updated to reflect the latest changes in the Fabric protocol.

Understanding the basics

I am not going to bore you with explaining what blockchain is and why it matters and explain the use cases of permissioned blockchain technology frameworks like Hyperledger Fabric. If you want to learn the basics of blockchain, Hyperledger Fabric, and its use cases. There is no better way than to study the official documentation here.

Installing the development environment

Installing one wrong package version might generate errors that can take days to debug. These steps have been tested to work well on Ubuntu 18.04 LTS.

Let us get started.

Installing cURL

cURL is a tool that is used to transfer data over the internet.

  1. Execute the command to install cURL.
sudo apt-get install curl

Installing Docker

Docker is a tool designed to make it easier to create, deploy, and run applications in virtual containers. We will use docker to set up simulate different peers in the network. We use docker CLI container to interact with the peers and ordering service, install and upgrade chaincode, and create and join channels.

1. Uninstall previous docker packages.

If you previously installed docker on your machine. You will need to remove all previous docker packages.

  • To identify what installed package you have:
dpkg -l | grep -i docker
  • If you see packages like docker-engine, docker, Write them like in the command below. It is possible that you have other packages of docker, you will need to uninstall them too.
sudo apt-get purge -y docker-engine docker docker-ce  
sudo apt-get autoremove -y --purge docker-engine docker docker-ce
  • The above commands will not remove images, containers, volumes, or user created configuration files on your host. If you wish to delete all images, containers, and volumes run the following commands:
sudo rm -rf /var/lib/docker
sudo rm /etc/apparmor.d/docker
sudo groupdel docker
sudo rm -rf /var/run/docker.sock

You have now successfully removed Docker from the system completely.

2. Set up the repository.

  • Update the apt package index:
sudo apt-get update
  • Install packages to allow apt to use a repository over HTTPS:
sudo apt-get install apt-transport-https ca-certificates curl gnupg agent software-properties-common
  • Add Docker’s official GPG key:
curl -fsSL | sudo apt-key add -
  • Use the following command to set up the stable repository
sudo add-apt-repository "deb [arch=amd64] $(lsb_release -cs) stable"

3. Install docker.

  • Update the apt package index:
sudo apt-get update
  • Install the latest version of Docker CE and containerd.
sudo apt-get install docker-ce docker-ce-cli

4. Verify that Docker CE is installed correctly.

Run the command to run hello-world docker image.

sudo docker run hello-world

5. Post installation steps for docker.

You need to eliminate the requirement of using sudo while working with docker

  • Create the docker group.
sudo groupadd docker
  • Add your user to the docker group.
sudo usermod -aG docker $USER
  • Log out and log back in.
  • Try running the docker command without sudo and verify if the above steps were successful.
docker run hello-world

Installing docker-compose

Docker Compose is a tool for running multi-container Docker applications. You need to define all the containers that your application depends on in a .yaml file. Then, with one single command, all the service are started and your application starts running.

  • Run this command to download the latest version of Docker Compose.
sudo curl -L "$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
  • Apply executable permissions to the binary.
sudo chmod +x /usr/local/bin/docker-compose
  • Verify your installation.
docker-compose --version

Installing Go programming language.

Go language is used to write chaincode business logic for the channels. You can also write chaincode in Node.js and Java. Whichever language you decide to use, you need to set up the $GOPATH.

  • Install go-lang from the repository.
sudo apt-get install golang-go
  • Open the file~/.profile file.
nano ~/.profile
  • Add these lines at the bottom of the file.
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
  • Save the file and exit with CTRL + X, press Y, and then press ENTER.
  • On the command line, update your system variables.
source ~/.profile

Installing Node.js package manager.

1. Installing NPM

  • To install the LTS release, use this command. Using the right npm package might save you hours debugging later down the line.
curl -sL | sudo bash -
  • To install, run the command below.
sudo apt install nodejs
  • Verify that npm and node.js have been installed.
node -v
npm -v

1. Post installation steps for NPM.

You need to set a new prefix for npm to eliminate the need of using sudo while installing packages.

  • Go to your home directory and create a directory for global installations.
mkdir ~/.npm-global
  • Configure npm to use the new directory path for installations.
npm config set prefix '~/.npm-global'
  • Open the file~/.profile file.
nano ~/.profile
  • Add this line at the bottom of the file.
export PATH=~/.npm-global/bin:$PATH
  • Save the file and exit with CTRL + X, press Y, and then press ENTER.
  • On the command line, update your system variables:
source ~/.profile

Installing Hyperledger Fabric packages.

The documentation of Hyperledger Fabric provides a script that will download and install samples and binaries to your system. These sample applications installed are useful to learn more about the capabilities and operations of Hyperledger Fabric.

  • Go to your home directory and execute the following command.
curl -sSL | bash -s 1.4.0

This will install 1.4 version of Hyperledger Fabric binaries.

The command above downloads and executes a bash script that will download and extract all of the platform-specific binaries you will need to set up your network.

It also retrieves some executable binaries that are needed in development and places them in the bin sub-directory of the current working directory.

  • To set these binaries to be run from anywhere on your machine. Open the file~/.profile file.
nano ~/.profile
  • Add this line at the bottom.
export PATH=~/fabric-samples/bin:$PATH
  • Save the file and exit with CTRL + X, press Y, and then press ENTER.
  • On the command line, update your system variables:
source ~/.profile

Run the sample network

  • Go to the first-network directory.
cd fabric-samples/first-network
  • Run the following command to generate crypto materials, start the network, and install chaincode.
./ up

The above command will bootstrap a sample network with fabcar chaincode installed. You can head to here to learn more about the network that we have just started.


After a year of development on Hyperledger Fabric framework, I have realized the importance of getting small things right when setting up the environment. Many errors that you might face during development might well be due to the mistakes in setting up the environment.

I hope this guide will help beginners starting to learn this new technology. Please feel free to point out mistakes in this guide.

Get in touch

Interested in starting your own blockchain project, but don’t know how? Get in touch at