In this post I'm showing you how to setup a basic system with Ubuntu and Virtualbox with all prerequisites installed for Hyperledger Fabric. The resulting virtual machine will serve as a basis for future experiments with the Linux Foundation's enterprise blockchain solution.

While I'm not describing how to install and setup the Hyperledger Fabric (HLF) network itself, I'll reference this post from others about HLF or other distributed ledgers when they're requiring a basic system setup.

If you're already familiar about how to install Ubuntu in Virtualbox, you may install it just the way you're used to and head directly to step 6, as there are no special requirements to run HLF. I'm giving the machines a fixed size virtual disk (dynamically allocated space might do the job as well) and more RAM as usually. That's it.


  1. Prerequisites
  2. Create Virtual Machine
  3. Install Ubuntu
  4. Install Guest Additions
  5. Setup Shared Folder & Clipboard
  6. Install Hyperledger Fabric Essentials
  7. Download Docker Images
  8. Taking a Snapshot

1. Prerequisites

Install Virtualbox and download the Ubuntu 18.04 (LTS) 64-Bit desktop image.

2. Create Virtual Machine

Press the "New"-button

After clicking the "New"-button a dialog opens. Enable the "Expert Mode", enter the options as follows and choose an appropriate name. If you can't afford 4GB RAM for each vm, you should be fine with 2GB for testing purposes, too.

In the next dialog you have to setup the virtual disk. Even though I'm usually selecting "Dynamically allocated", I'm going to use a fixed size disk this time for maximum performance. Otherwise, the virtual disk container needs to grow dynamically each time we store more data (which is not too uncommon on HLF nodes ­čśť).

Now as we finished the container's setup, we need to tell it to boot up from our previously downloaded Ubuntu image. Click on the newly created machine and then on the "Settings"-button.

Click the "Settings"-button

On the next window, select the "Storage" tab on the left. Click on the empty disc symbol in the middle of the screen, then click the disc-icon on the right to select the .iso file of Ubuntu. Don't forget to select the "Live CD/DVD" checkbox. Click "OK".

3. Install Ubuntu

Now double-click the machine to start. It will automatically boot the Ubuntu Live system. From now on, I'm skipping description and screenshots of every step except the more interesting ones.

Let's choose a "Minimal installation" and enable third-party software.

Keep the default selection "Erase disk and install Ubuntu" when asked for the installation type. During the installation process you'll be asked "Who are you?". Choose meaningful names here so it's easier to distinguish the machines of different organizations. As I'm using these virtual machines only for testing purposes, I'm using the organization's name as password.

Take a breath of fresh air while the system is being installed...

brown trees field under white sky
Photo by Annette Schuman

After the installation finished and the system rebooted, we're faced with the Ubuntu desktop. If you're prompted for new updates, confirm the immediate installation.

The next step is to install the Guest Additions, which are enabling some features like resolution adjustment, shared folders and a shared clipboard.

4. Install Guest Additions

On the menu bar, click "Devices" > "Insert Guest Additions CD image...". You'll be prompted for the installation automatically.

When clicking on "Run" you're probably faced with the same error message like me:

This system is currently not set up to build kernel modules.
Please install the gcc make perl packages from your distribution.
Press Return to close this window...

Ok, let's do that. Open the terminal via [Alt]-[F2], type gnome-terminal followed by [Enter]. Then install the required packages:

sudo apt-get update
sudo apt-get install build-essential gcc make perl dkms

After reboot, the Guest Additions CD is already mounted. Just double click it at the desktop. In the opened window click on "Run Software" at the top right.

After the installation has been finished, you can scale the virtual machine's window and Ubuntu's resolution will be adjusted automatically.

5. Setup Shared Folder & Clipboard

As we might need to exchange the public keys from our HLF identities of different virtual machines later, we're going to setup a shared folder. This allows us for easy file exchange between the host and the guest system. The shared clipboard also makes our lives easier for copying commands from this post into the guest system.

On the menu bar click "Devices" > "Shared folders" > "Shared Folders Settings...".
There are two types of shared folders. "Machine Folders" are permanent folders that are shared until you remove them. "Transient Folders" are temporary and are automatically removed when you restart or shut down the virtual machine.

Press the "Add shared folder"-button on the right side.

I'm creating a new folder on my host system specifically for this guest, e.g. /home/user/VirtualBox-Shared/HLF-A. Select "Auto-mount", "Make Permanent" and enter the mount point /mnt/shared.

Then again on the menu bar, select "Devices" > "Shared Clipboard" > "Bidirectional". This allows us to use the clipboard from host to guest and vice versa.

Both features are enabled immediately without restart.

6. Install Hyperledger Fabric Essentials

Now comes the fun part! We're going to install everything we'll need later to setup a HLF network.

Open a terminal within the guest system and curl, docker and docker-compose:

$ sudo apt-get install curl docker docker-compose

Validate that we're above the required versions of Docker 17.06.2-ce and Docker Compose 1.14.0:

$ docker --version
Docker version 18.06.1-ce, build e68fc7a

$ docker-compose --version
docker-compose version 1.17.1, build unknown

In order to connect to the Docker daemon socket our user needs to be in the docker group:

$ sudo usermod -a -G docker $USER
$ reboot

Install Go

We also want to install the Go programming language which HLF is written in. We might even choose to write chaincode in Go. However, Ubuntu's repository doesn't provide the recommended version of 1.11.x. So we have to install it manually.
First go to the Go download page and copy the url of the latest go1.11.x.linux-amd64.tar.gz file. Then in our guest's terminal:

$ wget

Compare the SHA256 checksum:

$ sha256sum go1.11.5.linux-amd64.tar.gz 
ff54aafedff961eb94792487e827515da683d61a5f9482f668008832631e5d25  go1.11.5.linux-amd64.tar.gz

Next, unpack the package and move the go directory to /usr/local.

$ tar -xvf go1.11.5.linux-amd64.tar.gz
$ sudo chown -R root:root ./go
$ sudo mv go /usr/local

Last but not least, let's set some paths for Go. Open the .profile file in your preferred editor:

$ nano ~/.profile

Add the following to the end of the file:

# Set Go paths
export GOROOT=/usr/local/go
export GOPATH=$HOME/go
export PATH=$PATH:$GOROOT/bin:$GOPATH/bin

Save + close the file and apply changes by sourcing it:

$ source ~/.profile

Install Node.js Runtime, NPM & Typescript

You only need this if you're planning to write chaincode in either Javascript or Typescript. As this is my personal preference (I've got far more experience in those than in Go), I'm going with it. First, install the Node Version Manager:

$ curl -o- | bash

Close and re-open the terminal, so that the nvm command is available. Then install and use the latest LTS of node:

$ nvm install --lts

$ node --version

$ npm --version

After all we can install the Typescript compiler globally:

$ npm i -g typescript
$ tsc --version
Version 3.3.3

7. Download Docker Images

Hyperledger provides a bootstrap script, which assists us in downloading all available docker images (peer, orderer, ca, couchdb, ...). Enter the following commands in your terminal:

$ mkdir fabric && cd fabric
$ curl -sSL | bash -s -- -s 1.4.0

This will download all the images and platform specific binaries while skipping the cloning of the samples repository. If you want them as well, just remove the -s right before the version string.

8. Taking a Snapshot

At this point we have all tools available we need for setting up our Fabric network. Let's take a snapshot from this state, as it will serve as our basic system setup for future tutorials.

Select the virtual machine, then on the menu bar "Snapshot" > "Take".

Enter a meaningful name like "Basic System" for easy identification and press OK.

Now you have a Hyperledger Fabric ready virtual machine, which you can clone for your experiments. Have fun and don't miss out my upcoming posts!