Skill Level: Intermediate

We show you how to setup and deploy Hyperledger Explorer. In doing so, you learn how to connect Explorer with Fabric and build and run blockchain applications.


To follow and complete this recipe, you need to have good knowledge of blockchain, Hyperledger transactions, JavaScript as well as basic knowledge of Linux.


  1. Hyperledger Explorer Background

    Hyperledger Explorer is a powerful utility that allows users to create user-friendly web-based applications. It is a blockchain dashboard and provides the ability to view, invoke, deploy, and query raw blockchain data and network information, including block details, chain codes, and transactions stored in the ledger.

    For those who are not familiar with Hyperledger project Intro to Hyperledger Family and Hyperledger Blockchain Ecosystem and Hyperledger Design Philosophy and Framework Architecture articles are strongly recommended.

    Hyperledger Explorer is a highly maintainable and open source browser that can be configured and built natively on macOS and Ubuntu. At the time of writing, Hyperledger Explorer has not yet gone live. The latest release, v0.3.8, supports Fabric v1.3.

    It is common to encounter errors here and there, especially around issues related to versions and/or setting up environments. To save time while debugging, I have included notes, along with recommended fixes, for some of errors you might run into while walking through this recipe.

    To follow and understand this recipe, reading the following tutorials: Overview of Hyperledger Explorer and its Development Environment, Installing Hyperledger Explorer and Setting up the Database as well as Configuring Hyperledger Explorer with Fabric are highly recommended.
    In this recipe, we build Hyperledger Explorer which is essential step before deploying a Hyperledger Explorer application.

  2. Hyperledger Explorer Development

    Execute the following commands:
    1. You will notice that all is running as expected:


    cd ~/blockchain-explorer/

     sudo npm install

    > pkcs11js@1.0.16 install /home/ubuntu/blockchain-explorer/node_modules/pkcs11js
    > node-gyp rebuild
    make: Entering directory ‘/home/ubuntu/blockchain-explorer/node_modules/pkcs11js/build’

    make: Leaving directory ‘/home/ubuntu/blockchain-explorer/node_modules/pkcs11js/build’

    added 2 packages from 1 contributor in 392.181s


    2. Otherwise, if you have been running everything with sudo, you might get a permission-denied error, as follows:

    dtrace-provider@0.8.7 install /home/ubuntu/blockchain-explorer/node_modules/dtrace-provider

    node-gyp rebuild || node suppress-error.js

    gyp ERR! configure error
    gyp ERR! stack Error: EACCES: permission denied, mkdir ‘/home/ubuntu/blockchain-explorer /node_modules/dtrace-provider/build’

    gyp ERR! cwd /home/ubuntu/blockchain-explorer/node_modules/pkcs11js gyp ERR! node -v v8.15.0
    gyp ERR! node-gyp -v v3.8.0
    gyp ERR! not ok
    npm ERR! code ELIFECYCLE
    npm ERR! errno 1
    npm ERR! pkcs11js@1.0.16 install: `node-gyp rebuild`
    npm ERR! Exit status 1
    npm ERR!
    npm ERR! Failed at the pkcs11js@1.0.16 install script.
    npm ERR! This is probably not a problem with npm. There is likely additional logging output above.


    3. Execute the following commands to change the ownership, and then rerun the install:


    $sudo chown -R $USER:$(id -gn $USER) ./node_modules $ npm install


    4. Another possible build error you might face is if you are working on a new machine or a new EC2 instance:


    pkcs11js@1.0.16 install /home/ubuntu/blockchain-explorer/node_modules/pkcs11js

     node-gyp rebuild

    gyp ERR! build error

    gyp ERR! stack Error: not found: make gyp ERR! stack at getNotFoundError (/usr/lib/node_modules/npm/node_modules/which /which.js:13:12)

    gyp ERR! stack at F


    gyp ERR! stack at E


    gyp ERR! stack at


    gyp ERR! stack at


    gyp ERR! stack at


    gyp ERR! stack at FSReqWrap.oncomplete (fs.js:152:21)

    gyp ERR! System Linux 4.4.0-1075-aws

    gyp ERR! command “/usr/bin/node”

    “/usr/lib/node_modules/npm/node_modules/node-gyp/bin/node-gyp.js” “rebuild”

    gyp ERR! cwd /home/ubuntu/blockchain-explorer/node_modules/pkcs11js gyp ERR! node -v v8.15.0

    gyp ERR! node-gyp -v v3.8.0

    gyp ERR! not ok

    npm ERR! code ELIFECYCLE

    npm ERR! errno 1

    npm ERR! pkcs11js@1.0.16 install: `node-gyp rebuild` npm ERR! Exit status 1


    5. This means you have not got the GNU make tool installed. Executing the following command should fix the issue:

    $ sudo apt install build-essential

    6. We will now build and run the explorer tester:


    cd blockchain-explorer/app/test

     npm install

    npm WARN hyperledger-explorer-test@0.3.3 No repository field. added 384 packages from 844 contributors in 7.161s


    7. Run test, as follows:

    npm run test


    8. You might run into the following authentication error for postgres:


    (node:12316) UnhandledPromiseRejectionWarning: error: password authentication failed for user “postgres”
    at Connection.parseE (/home/ubuntu/blockchain-explorer/app/test/node_modules/pg/lib/connection.js:553:11) at Connection.parseMessage (/home/ubuntu/blockchain-explorer/app/test/node_modules/pg/lib/connection.js:378:19) at Socket.<anonymous> (/home/ubuntu/blockchain-explorer/app/test/node_modules/pg/lib/connection.js:119:22) at emitOne (events.js:116:13)
    at Socket.emit (events.js:211:7)
    at addChunk (_stream_readable.js:263:12)
    at readableAddChunk (_stream_readable.js:250:11)
    at Socket.Readable.push (_stream_readable.js:208:10)
    at TCP.onread (net.js:601:20)
    (node:12316) UnhandledPromiseRejectionWarning: Unhandled promise rejection. This error originated either by throwing inside of an async function without a catch block, or by rejecting a promise which was not handled with .catch(). (rejection id: 1)
    (node:12316) [DEP0018] DeprecationWarning: Unhandled promise rejections are deprecated. In the future, promise rejections that are not handled will terminate the Node.js process with a non-zero exit code.


    9. If so, execute the following command to change the MD5 authentication to trust for a quick fix:


    sudo sed -i.bak ‘/^host.*md5/ s/md5/trust/’ /etc/postgresql/*/main/pg_hba.conf

    sudo service postgresql restart


    10. Once PostgreSQL restarts, you will have to rerun test:

    $ sudo npm run test

    hyperledger-explorer-test@0.3.3 test /home/ubuntu/blockchain-explorer/app/test

     mocha *.js –exit

    GET /api/blockAndTxList/:channel/:blocknum should return blockandtx

    when it is completed, you will see the status: 19 passing (686ms)



    tests 1

     pass 1



    11. From the same Terminal window, install client, as follows:

    cd ../../client/

     npm install

    > jss@9.8.7 postinstall /home/ubuntu/blockchain-explorer/client/node_modules/jss

    > node -e “console.log(‘\u001b[35m\u001b[1mLove JSS? You can now support us on open collective:\u001b[22m\u001b[39m\n > \u001b[34mhttps://opencollective.com/jss/donate\u001b[0m’]”


    added 2227 packages from 1353 contributors in 60.754s


    12. Run some tests, as follows:

    $ npm test — -u -coverage

    hyperledger-explorer-client@0.3.8 test /home/ubuntu/blockchain-explorer/client


    react-scripts test –env=jsdom “-u” “–coverage”

    you might see some console warnings, ignore it Test Suites: 26 passed, 26 total


    Tests: 171 passed, 171 total

    Snapshots: 0 total

    Time: 24.283s, estimated 198s Ran all test suites.


    13. We can now carry out build:

    $ npm run build

    hyperledger-explorer-client@0.3.8 build /home/ubuntu/blockchain-explorer/client

     react-scripts build

    Creating an optimized production build…

    Compiled successfully.



    Note: The client build takes time to complete. However, if it takes more than 5 minutes or so and the system appears to freeze without responding, this might be an indication that your current system does not have enough RAM to handle it.

    So far we have learned how to i- Install Hyperledger Explorer and its pre-requisite environment, ii- Configure the explorer to connect to a blockchain network like Fabric and iii- Build a Hyperledger Explorer application. The next step is to run the Hyperledger Explorer application. Learning blockchain development in bootcamp style is the best way to master Hyperledger. Here is a list of top bootcamp schools that offer great training resources.

    This tutorial is written in collaboration with Brian Wu who is a senior Hyperledger instructor at Coding Bootcamps school in Washington DC.

Join The Discussion