blockchain-explorer

Blockchain Explorer

Current Release

Legacy Releases (NOT SUPPORTED)

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

• Docker
• Docker Compose

  • Note(for v2.0.0 and above): The following docker images are automatically pulled from GHCR instead of Docker Hub when starting docker-compose.

    • Hyperledger Explorer ghcr repository
    • Hyperledger Explorer PostgreSQL ghcr repository

  • Note(for v1.1.8 and below): 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

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)

  bash复制

  mkdir explorer
  cd explorer

• Copy the following files from the repository

  • .env
  • docker-compose.yaml
  • examples/net1/connection-profile/test-network.json
  • examples/net1/config.json
  bash复制

  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)

  bash复制

  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

  yaml复制

      networks:
      mynetwork.com:
          external:
              name: fabric_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.

  bash复制

  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.

  yaml复制

  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:

  json复制

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

  After:

  json复制

  "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:

  bash复制

  $ docker-compose up -d

Clean up

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

  bash复制

  $ 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:

  bash复制

  $ docker-compose down -v

Quick start (using codebase)

Prerequisites

• Nodejs 12, 14 and 16 (12.22.12, 14.21.3, 16.20.1 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.

  json复制

  "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:

    bash复制

    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:

  json复制

  {
      "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

  bash复制

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

• MacOS

  bash复制

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

Expected output

…

(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 inst