Installing a development environment

Installing and developing with Hyperledger Composer

Follow the instructions below to get the required Hyperledger Composer development tools and stand up a Hyperledger Fabric.

Before you begin

To run Hyperledger Composer and Hyperledger Fabric, we recommend you have at least 4Gb of memory.

The following are prerequisites for installing the required development tools:

  • Operating Systems: Ubuntu Linux 14.04 / 16.04 LTS (both 64-bit), or Mac OS 10.12
  • Docker Engine: Version 17.03 or higher
  • Docker-Compose: Version 1.8 or higher
  • Node: 8.9 or higher (note version 9 is not supported)
  • npm: v5.x
  • git: 2.9.x or higher
  • Python: 2.7.x
  • A code editor of your choice, we recommend VSCode.

**If installing Hyperledger Composer using Linux, be aware of the following advice:

  • Login as a normal user, rather than root.
  • Do not su to root.
  • When installing prerequisites, use curl, then unzip using sudo.
  • Run as a normal user. It may prompt for root password as some of it's actions are required to be run as root.
  • Do not use npm with sudo or su to root to use it.
  • Avoid installing node globally as root.**

If you're running on Ubuntu, you can download the prerequisites using the following commands:

curl -O

chmod u+x

Next run the script - as this briefly uses sudo during its execution, you will be prompted for your password.


If you're running Mac OS X, you can follow the installation guide for Mac OS X pre-requisites.

Step 1: Installing Hyperledger Composer development tools

The development tools you'll need can all be installed (as a non-privileged user eg non-root) with npm install -g.

  1. To install composer-cli run the following command:

    npm install -g composer-cli

    The composer-cli contains all the command line operations for developing business networks.

  2. To install generator-hyperledger-composer run the following command:

    npm install -g generator-hyperledger-composer

    The generator-hyperledger-composer is a Yeoman plugin that creates bespoke applications for your business network.

  3. To install composer-rest-server run the following command:

    npm install -g composer-rest-server

    The composer-rest-server uses the Hyperledger Composer LoopBack Connector to connect to a business network, extract the models and then present a page containing the REST APIs that have been generated for the model.

  4. To install Yeoman run the following command:

    npm install -g yo

    Yeoman is a tool for generating applications. When combined with the generator-hyperledger-composer component, it can interpret business networks and generate applications based on them.

Optional development tools

  1. If you use VSCode, install the Hyperledger Composer VSCode plugin from the VSCode marketplace.

  2. If you want to run the connect to a business network using the Playground locally, install the composer-playground using the following command.

    npm install -g composer-playground
  3. To run the playground locally run the following command:


    The playground should open automatically at the following address: http://localhost:8080/login

Step 2: Starting Hyperledger Fabric

If you've installed the Hyperledger Composer Playground locally you'll need to close the containers by using the following scripts.

Please note: These commands will kill and remove all running containers, and should remove all previously created Hyperledger Fabric chaincode images.

docker kill $(docker ps -q)
docker rm $(docker ps -aq)
docker rmi $(docker images dev-* -q)
  1. In a directory of your choice (will assume ~/fabric-tools) get the zip file that contains the tools to install Hyperledger Fabric v1.0.

    mkdir ~/fabric-tools && cd ~/fabric-tools
    curl -O

    A tar.gz file is also available

    mkdir ~/fabric-tools && cd ~/fabric-tools
    curl -O
    tar xvzf fabric-dev-servers.tar.gz
  2. If this is the first time, you'll need to download the fabric runtime first. If you have already downloaded it, then start the fabric environment, and create a Hyperledger Composer profile. After that you can then choose to stop the fabric, and start it again later. Alternatively to completely clean up you can teardown the Hyperledger Fabric and the Hyperledger Composer profile.

    All the scripts will be in the directory ~/fabric-tools A typical sequence for Hyperledger Composer use would be

    cd ~/fabric-tools

    Then at the end of your development session

    cd ~/fabric-tools

Please note: The development environment created will include a PeerAdmin identity including the cryptographic material necessary for deploying business networks.

Script details


This diagram explains the order in which the scripts can be run.

Downloading Fabric

Issue from the fabric-tools directory ./

Starting Fabric

Issue from the fabric-tools directory ./

Stop Fabric

Issue from the fabric-tools directory ./

Create PeerAdmin Card

Create a business network card for the peer administrator specific to the Hyperledger Fabric instance running. ./

Note: this creates and imports a business network card to connect to the development fabric you've already started.

Teardown Fabric

Issue from the fabric-tools directory ./

What next?