Hyperledger Explorer

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

Update! Hyperledger 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

Hyperledger 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
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 refer more detail of each configuration, please refer README-CONFIG.md.

Quick start (using Docker)

Prerequisites

Docker
Docker Compose
- Note: The following docker images are automatically pulled from Docker Hub when starting docker-compose.
  - Hyperledger Explorer docker repository
  - Hyperledger Explorer PostgreSQL docker repository

Start Hyperledger Fabric network

In this guide, we assume that you've already started test network by following Hyperledger Fabric official tutorial.

Configure

Copy the following files from 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 (e.g. crypto-config/, organizations/) from your fabric network

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 network name and path to volumes to be mounted on Explorer container (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

When you connect Explorer to your fabric network through 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
```

Edit path to admin certificate and secret (private) key in the connection profile (test-network.json). You need to specify with the absolute path on Explorer container.

  "organizations": {
    "Org1MSP": {
      "adminPrivateKey": {
        "path": "/tmp/crypto/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/priv_sk"
      ...
      ...
      "signedCert": {
        "path": "/tmp/crypto/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/signcerts/Admin@org1.example.com-cert.pem"
      }

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

In this guide, we assume that you've already started 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 configure database settings is to use environment variables, example of settings:
```
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 case 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 only value of the key name
- profile is the location of your connection profile, you can change 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 ussually ends with _sk, for example: /fabric-path/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/priv_sk
- adminUser and adminPassword is the credential for user of Explorer to login 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

Connect to the PostgreSQL database and run DB status commands:

$ sudo -u postgres psql -c '\l'
                                List of databases
      Name      |  Owner   | Encoding | Collate |  Ctype  |   Access privileges
----------------+----------+----------+---------+---------+-----------------------
 fabricexplorer | hppoc    | 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 fabricexplorer -c '\d'
                   List of relations
 Schema |           Name            |   Type   | Owner
--------+---------------------------+----------+-------
 public | blocks                    | table    | hppoc
 public | blocks_id_seq             | sequence | hppoc
 public | chaincodes                | table    | hppoc
 public | chaincodes_id_seq         | sequence | hppoc
 public | channel                   | table    | hppoc
 public | channel_id_seq            | sequence | hppoc
 public | orderer                   | table    | hppoc
 public | orderer_id_seq            | sequence | hppoc
 public | peer                      | table    | hppoc
 public | peer_id_seq               | sequence | hppoc
 public | peer_ref_chaincode        | table    | hppoc
 public | peer_ref_chaincode_id_seq | sequence | hppoc
 public | peer_ref_channel          | table    | hppoc
 public | peer_ref_channel_id_seq   | sequence | hppoc
 public | transactions              | table    | hppoc
 public | transactions_id_seq       | sequence | hppoc
 public | write_lock                | table    | hppoc
 public | write_lock_write_lock_seq | sequence | hppoc
(18 rows)

Build Hyperledger Explorer

Important: repeat the below steps after every git pull

./main.sh install
- To install, run tests, and build project

./main.sh clean
- To clean the /node_modules, client/node_modules client/build, client/coverage, app/test/node_modules directories

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

Run Hyperledger Explorer

Run Locally in Same Location

Modify app/explorerconfig.json to update sync settings.
```
"sync": {
  "type": "local"
}
```
npm start
- It will have the backend and GUI service up
npm run app-stop
- It will stop the node server

Note: If Hyperledger Fabric network is deployed on other machine, 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 Hyperledger Fabric network is deployed on other machine, please define the following environment variable

$ DISCOVERY_AS_LOCALHOST=false ./syncstart.sh

Configuration

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

Logs

Please visit the ./logs/console folder to view the logs relating to 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/.

Y-Liu0722/blockchain-explorer

Hyperledger Explorer

Release Notes

Quick start (using Docker)

Prerequisites

Start Hyperledger Fabric network

Configure

Start container services

Clean up

Quick start (using codebase)

Prerequisites

Start Hyperledger Fabric network

Clone GIT Repository

Database Setup

Update configuration

Run create database script:

Build Hyperledger Explorer

Run Hyperledger Explorer

Run Locally in Same Location

Run Standalone in Different Location

Configuration

Logs

Troubleshooting

License