Skip to content

ImperialCollegeLondon/blocc-explorer

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Blockchain Explorer

GitHub release (latest SemVer) Docker Pulls node-current
Build Status CII Best Practice Documentation Status Language grade: JavaScript Total alerts Quality Gate Status

Explorer is a simple, powerful, easy-to-use, well-maintained, open-source utility to browse activity on the underlying blockchain network. Users can configure and build Hyperledger Explorer on macOS and Ubuntu.

Update! Explorer now can be used with Hyperledger Iroha. For Iroha support, please switch to iroha-integration branch and read this README for instructions on how to use it.

Release Notes

Explorer Version Fabric Version Supported NodeJS Version Supported
v1.1.8 (Aug 14, 2021) v1.4 to v2.3 ^12.13.1, ^14.13.1, ^16.14.1
v1.1.7 (Jul 04, 2021) v1.4 to v2.3 ^12.13.1, ^14.13.1
v1.1.6 (Jun 06, 2021) v1.4 to v2.3 ^12.13.1, ^14.13.1
v1.1.5 (Apr 20, 2021) v1.4 to v2.3 ^12.13.1, ^14.13.1
v1.1.4 (Jan 29, 2021) v1.4 to v2.2 ^12.13.1, ^14.13.1
v1.1.3 (Sep 28, 2020) v1.4.0 to v2.2.0 12.16.x
v1.1.2 (Aug 12, 2020) v1.4.0 to v2.2.0 12.16.x

There are 2 options to get Explorer started. Following are the software dependencies required for each option. And if you want to know more about each configuration, please refer README-CONFIG.md.

Quick start (using Docker)

Prerequisites

Start Hyperledger Fabric network

This guide assumes that you've already started the test network by following Hyperledger Fabric official tutorial.

Configure

  • Create a new directory (e.g. explorer)

    mkdir explorer
    cd explorer
  • Copy the following files from the repository

    wget https://raw.githubusercontent.com/hyperledger/blockchain-explorer/main/examples/net1/config.json
    wget https://raw.githubusercontent.com/hyperledger/blockchain-explorer/main/examples/net1/connection-profile/test-network.json -P connection-profile
    wget https://raw.githubusercontent.com/hyperledger/blockchain-explorer/main/docker-compose.yaml
  • Copy entire crypto artifact directory (organizations/) from your fabric network (e.g /fabric-samples/test-network)

    cp -r ../fabric-samples/test-network/organizations/ .
  • Now, you should have the following files and directory structure.

    docker-compose.yaml
    config.json
    connection-profile/test-network.json
    organizations/ordererOrganizations/
    organizations/peerOrganizations/
    
  • Edit environmental variables in docker-compose.yaml to align with your environment

        networks:
        mynetwork.com:
            external:
                name: net_test
    
        ...
    
        services:
          explorer.mynetwork.com:
    
            ...
    
            volumes:
              - ./config.json:/opt/explorer/app/platform/fabric/config.json
              - ./connection-profile:/opt/explorer/app/platform/fabric/connection-profile
              - ./organizations:/tmp/crypto
              - walletstore:/opt/explorer/wallet

    An alternative option is to export environment variables in your shell.

    export EXPLORER_CONFIG_FILE_PATH=./config.json
    export EXPLORER_PROFILE_DIR_PATH=./connection-profile
    export FABRIC_CRYPTO_PATH=./organizations
  • When you connect Explorer to your fabric network through the bridge network, you need to set DISCOVERY_AS_LOCALHOST to false for disabling hostname mapping into localhost.

    services:
    
      ...
    
      explorer.mynetwork.com:
    
        ...
    
        environment:
          - DISCOVERY_AS_LOCALHOST=false
  • Replace the user's certificate with an admin certificate and a secret (private) key in the connection profile (test-network.json). You need to specify the absolute path on the Explorer container.

    Before:

    "adminPrivateKey": {
        "path": "/tmp/crypto/peerOrganizations/org1.example.com/users/[email protected]/msp/keystore/priv_sk"
    }

    After:

    "adminPrivateKey": {
        "path": "/tmp/crypto/peerOrganizations/org1.example.com/users/[email protected]/msp/keystore/priv_sk"
    }

    Make sure you replace all paths.

Start container services

  • Run the following to start up explore and explorer-db services after starting your fabric network:

    $ docker-compose up -d

Clean up

  • To stop services without removing persistent data, run the following:

    $ docker-compose down
  • In the docker-compose.yaml, two named volumes are allocated for persistent data (for Postgres data and user wallet). If you would like to clear these named volumes up, run the following:

    $ docker-compose down -v

Quick start (using codebase)

Prerequisites

  • Nodejs 10 and 12 (10.19 and 12.16 tested)
  • PostgreSQL 9.5 or greater
  • jq
  • Linux-based operating system, such as Ubuntu or MacOS
  • golang (optional)
    • For e2e testing

Start Hyperledger Fabric network

This guide assumes that you've already started the test network by following Hyperledger Fabric official tutorial.

Clone GIT Repository

Clone this repository to get the latest using the following command.

$ git clone https://github.com/hyperledger/blockchain-explorer.git
$ cd blockchain-explorer

Database Setup

$ cd blockchain-explorer/app
  • Modify app/explorerconfig.json to update PostgreSQL database settings.

    "postgreSQL": {
        "host": "127.0.0.1",
        "port": "5432",
        "database": "fabricexplorer",
        "username": "hppoc",
        "passwd": "password"
    }
    • Another alternative to configuring database settings is to use environment variables:

      export DATABASE_HOST=127.0.0.1
      export DATABASE_PORT=5432
      export DATABASE_DATABASE=fabricexplorer
      export DATABASE_USERNAME=hppoc
      export DATABASE_PASSWD=pass12345

    Important repeat after every git pull (in some cases, you may need to apply permission to db/ directory, from blockchain-explorer/app/persistence/fabric/postgreSQL run: chmod -R 775 db/

Update configuration

  • Modify app/platform/fabric/config.json to define your fabric network connection profile:

    {
        "network-configs": {
            "test-network": {
                "name": "Test Network",
                "profile": "./connection-profile/test-network.json",
                "enableAuthentication": false
            }
        },
        "license": "Apache-2.0"
    }
    • test-network is the name of your connection profile and can be changed to any name
    • name is a name you want to give to your fabric network. You can change the only value of the key name
    • profile is the location of your connection profile. You can change the only value of the key profile
  • Modify connection profile in the JSON file app/platform/fabric/connection-profile/test-network.json:

    • Change fabric-path to your fabric network disk path in the test-network.json file:
    • Provide the full disk path to the adminPrivateKey config option. It usually ends with _sk, for example: /fabric-path/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/[email protected]/msp/keystore/priv_sk
    • exploreradmin and exploreradminpw is the credential for the user of Explorer to log in to the dashboard
    • enableAuthentication is a flag to enable authentication using a login page. Setting to false will skip authentication.

Run create database script:

  • Ubuntu

    $ cd blockchain-explorer/app/persistence/fabric/postgreSQL/db
    $ sudo -u postgres ./createdb.sh
    
  • MacOS

    $ cd blockchain-explorer/app/persistence/fabric/postgreSQL/db
    $ ./createdb.sh
    $ createdb `whoami`
    

Connect to the PostgreSQL database and run DB status commands. To export the settings from app/explorerconfig.json to the environment, run source app/exportConfig.sh; this will set $DATABASE_DATABASE and related envvars.

  • Ubuntu

    sudo -u postgres psql -c '\l'
    sudo -u postgres psql $DATABASE_DATABASE -c '\d'
  • MacOS

    psql -c '\l'
    psql $DATABASE_DATABASE -c '\d'

Expected output

$ sudo -u postgres psql -c '\l'
                                     List of databases
      Name      |        Owner        | Encoding | Collate |  Ctype  |   Access privileges
----------------+---------------------+----------+---------+---------+-----------------------
 fabricexplorer | $DATABASE_USERNAME  | UTF8     | C.UTF-8 | C.UTF-8 |
 postgres       | postgres            | UTF8     | C.UTF-8 | C.UTF-8 |
 template0      | postgres            | UTF8     | C.UTF-8 | C.UTF-8 | =c/postgres          +
                |                     |          |         |         | postgres=CTc/postgres
 template1      | postgres            | UTF8     | C.UTF-8 | C.UTF-8 | =c/postgres          +
                |                     |          |         |         | postgres=CTc/postgres
(4 rows)

$ sudo -u postgres psql $DATABASE_DATABASE -c '\d'
                   List of relations
 Schema |           Name            |   Type   |       Owner
--------+---------------------------+----------+-------------------
 public | blocks                    | table    | $DATABASE_USERNAME
 public | blocks_id_seq             | sequence | $DATABASE_USERNAME
 public | chaincodes                | table    | $DATABASE_USERNAME
 public | chaincodes_id_seq         | sequence | $DATABASE_USERNAME
 public | channel                   | table    | $DATABASE_USERNAME
 public | channel_id_seq            | sequence | $DATABASE_USERNAME
 public | orderer                   | table    | $DATABASE_USERNAME
 public | orderer_id_seq            | sequence | $DATABASE_USERNAME
 public | peer                      | table    | $DATABASE_USERNAME
 public | peer_id_seq               | sequence | $DATABASE_USERNAME
 public | peer_ref_chaincode        | table    | $DATABASE_USERNAME
 public | peer_ref_chaincode_id_seq | sequence | $DATABASE_USERNAME
 public | peer_ref_channel          | table    | $DATABASE_USERNAME
 public | peer_ref_channel_id_seq   | sequence | $DATABASE_USERNAME
 public | transactions              | table    | $DATABASE_USERNAME
 public | transactions_id_seq       | sequence | $DATABASE_USERNAME
 public | write_lock                | table    | $DATABASE_USERNAME
 public | write_lock_write_lock_seq | sequence | $DATABASE_USERNAME
(18 rows)

(On MacOS, expect to see your `whoami` rather than postgres. Entries with $DATABASE_USERNAME will have the valuei of that parameter, whether set as an environment variable or as a JSON keyval; it will not show the literal string.)

Build Hyperledger Explorer

Important: repeat the below steps after every git pull

From the root of the repository:

  • ./main.sh clean
    • To clean the /node_modules, client/node_modules client/build, client/coverage, app/test/node_modules directories
  • ./main.sh install
    • To install, run tests, and build project

Or

$ cd blockchain-explorer
$ npm install
$ cd client/
$ npm install
$ npm run build

Run Hyperledger Explorer

Run Locally in the Same Location

  • Modify app/explorerconfig.json to update sync settings.

    "sync": {
      "type": "local"
    }
  • npm start

    • It will have the backend and GUI service up, for as long as the process runs
  • npm run app-stop

    • It will stop the node server

Note: If the Hyperledger Fabric network is deployed on other machines, please define the following environment variable

$ DISCOVERY_AS_LOCALHOST=false npm start

Run Standalone in Different Location

  • Modify app/explorerconfig.json to update sync settings.

    "sync": {
      "type": "host"
    }
  • If the Hyperledger Explorer was used previously in your browser, be sure to clear the cache before relaunching

  • ./syncstart.sh

    • It will have the sync node up
  • ./syncstop.sh

    • It will stop the sync node

Note: If the Hyperledger Fabric network is deployed on other machines, please define the following environment variable

$ DISCOVERY_AS_LOCALHOST=false ./syncstart.sh

Updating Docker image

To build a new version of the Docker image, use npm run-script docker_build. This creates a new image, which will become hyperledger-explorer:latest (distinct from the canonical images, which are hyperledger/explorer, with a /). This is a distinct build from the local version used in the Quick Start process. Run this image with docker-compose down && docker-compose up -d; both commands are needed.

Configuration

Please refer README-CONFIG.md for more detail on each configuration.

Logs

  • Please visit the ./logs/console folder to view the logs relating to the console and ./logs/app to view the application logs, and visit the ./logs/db to view the database logs.

Troubleshooting

Please visit the TROUBLESHOOT.md to view the Troubleshooting TechNotes for Hyperledger Explorer.

License

Hyperledger Explorer Project source code is released under the Apache 2.0 license. The README.md, CONTRIBUTING.md files, and files in the "images", "snapshots" folders are licensed under the Creative Commons Attribution 4.0 International License. You may obtain a copy of the license, titled CC-BY-4.0, at http://creativecommons.org/licenses/by/4.0/.

About

No description, website, or topics provided.

Resources

License

Code of conduct

Security policy

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Languages

  • JavaScript 59.9%
  • TypeScript 30.8%
  • Shell 5.3%
  • Go 2.9%
  • CSS 0.5%
  • Dockerfile 0.3%
  • HTML 0.3%