Stand up a Hyperledger Fabric network on a single Ubuntu machine

Hyperledger fabric is an open-source blockchain application platform that provides a starting point for developing blockchain-based applications. When we refer to a Hyperledger Fabric network, we mean a running system that’s using Hyperledger Fabric.

Deploying a Fabric network, even with the bare minimum number of components, is not an easy task. The Fabric community has created a project called Cello to help blockchain application developers and operators in deploying Fabric networks of various sizes.

In this tutorial, we demonstrate how to use Cello to deploy a small Hyperledger Fabric (version 1.0.2) network, with all necessary components, to a single Ubuntu server, so you can begin to develop blockchain-based applications.

Learning objectives

In addition to having a running Hyperledger Fabric network, you will also accomplish the following:

  • Create an overlay network for your Fabric network.
  • Install and configure registrator and DNS services (so the Fabric containers can work together using container names instead of IP addresses).
  • Install and configure one node zookeeper and one node kafka cluster to serve Fabric orderers.
  • Install two peers and one orderer from two different organizations.
  • Create one channel and join two peers to the channel.
  • Install a simple chaincode onto both peers.
  • Instantiate the chaincode with the channel.


For this tutorial, we use VirtualBox, which can be used on a variety of Windows, Mac, and Linux operating systems. Specifically, the following is required:

  • VirtualBox version 5.1.0 or newer.
  • Enough memory to host a virtual machine with at least 4GB of memory.

Estimated time

It should take about one hour to complete this how-to.


Prepare your environment

  1. To create a clean VirtualBox Ubuntu 16.04 virtual machine, you can download VirtualBox and Ubuntu, to create a new virtual machine yourself. Alternatively, the premade image is made available to you for this exercise. Once downloaded, the image can be imported into VirtualBox by selecting File -> Import Appliance, and choosing the downloaded file.

  2. Start the virtual machine. If the premade image was used, the user name is ubuntu and the password is ps. If you did not use the premade image, then the username and password are likely different.

  3. Change the ssh_user in both the vars/vb.yml and the vars/vb1st.yml file. The password is not used by the Cello project.

Install dependencies and clone project Cello

  1. From your virtual machine, run the following commands. These commands install dependencies, grant the current user docker permission, and also clone project Cello.

     sudo apt-get update
     sudo apt-get install python-dev python-pip libssl-dev libffi-dev -y
     sudo pip install 'ansible>='
     sudo gpasswd -a $USER docker
     cd ~ && git clone
  2. Set up an SSH key pair and SSH agent key pair login.

     mkdir -p ~/.ssh && cd ~/.ssh && ssh-keygen -t rsa -f fd -P ""
     cat ~/.ssh/ >> ~/.ssh/authorized_keys
  3. Log out, log back in, and start up the SSH agent.

     eval $(ssh-agent -s) && ssh-add ~/.ssh/fd

Leverage Ansible to stand up the fabric network

  1. Create an Ansible run directory.

     mkdir -p ~/cello/src/agent/ansible/run
  2. Download the template file associated with this how-to and place it in the ~/cello/src/agent/ansible/run directory.

     cd ~/cello/src/agent/ansible/run
     # the runhosts.tpl file should be here
  3. Run the following commands to create a runhosts file.

     cd ~/cello/src/agent/ansible
     ipaddr=$(ip -4 addr show | awk -F '/' '/inet / {print $1}' | grep -v '' | awk -F ' ' '{print $2;exit}')
     sed "s/\$ip/$ipaddr/g" run/runhosts.tpl > run/runhosts
  4. Stand up the fabric network.

     ansible-playbook -i run/runhosts -e "mode=apply env=vb" initcluster.yml --skip-tags="resetconn"
     ansible-playbook -i run/runhosts -e "mode=apply env=bc2nd" setupfabric.yml

Verify the fabric network is running correctly

  1. Verify all the containers are running by issuing the following command, sample output included.

     $ docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Image}}'
     The results:
     NAMES                                STATUS              IMAGE
     dev-peer1st-mad-firstchaincode-1.0   Up 6 minutes        dev-peer1st-mad-firstchaincode-1.0-xxxx
     peer2nd-mad                          Up 7 minutes        hyperledger/fabric-peer:x86_64-1.0.2
     peer1st-mad                          Up 7 minutes        hyperledger/fabric-peer:x86_64-1.0.2
     1storderer-sin                       Up 7 minutes        hyperledger/fabric-orderer:x86_64-1.0.2
     kafka1st                             Up 7 minutes        hyperledger/fabric-kafka:x86_64-1.0.2
     zookeeper1st                         Up 7 minutes        hyperledger/fabric-zookeeper:x86_64-1.0.2
     registrator.fabric001                Up 15 minutes       email4tong/registrator:v10
     skydns.fabric001                     Up 15 minutes       skynetservices/skydns:2.5.3a
  2. Verify that the chaincode container is running and produced a correct log entry.

     $ docker logs dev-peer1st-mad-firstchaincode-1.0
     The results:
     ex02 Init
     Aval = 100, Bval = 200
  3. Query the chaincode

A successful chaincode query means that the chaincode is deployed and running successfully on peers. To query the installed and instantiated chaincode in earlier steps, you can follow the steps below::

$ docker exec -it peer1st-mad bash
peer chaincode query -C firstchannel -n firstchaincode -c '{"Args":["query","a"]}'

The results: Notice that the time stamp will be different on your machine

Query Result: 100
2017-11-09 16:38:11.056 UTC [main] main -> INFO 007 Exiting.....

Develop your own blockchain application

With your environment up and running, you can now create your own channels, chaincode, and blockchain application. If you need more information on chaincode, and how to develop one, you can read the Chaincode tutorial.

Destroy the Fabric network

To take down the Fabric network, issue the following commands:

ansible-playbook -i run/runhosts -e "mode=destroy env=bc2nd" setupfabric.yml
ansible-playbook -i run/runhosts -e "mode=destroy env=vb" initcluster.yml


Congratulations. You now have deployed a small Hyperledger Fabric network, with all necessary components, to a single Ubuntu server, so you can begin developing blockchain-based applications.