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.
Table of Contents
- 1.0 Release Notes
- 2.0 Directory Structure
- 3.0 Dependencies
- 4.0 Clone GIT Repository
- 5.0 Database Setup
- 5.1 Authorization Configuration
- 6.0 Fabric Network Setup
- 7.0 Configure Hyperledger Fabric
- 7.1 Optional: Configure Fabcar Sample
- 7.2 Optional: Configure Balance Transfer Sample
- 7.3 Optional: Configure for monitoring multiple organizations
- 8.0 Hyperledger Composer Setup
- 9.0 Optional: Hyperledger Cello Setup
- 10.0 Build Hyperledger Explorer
- 10.1 Optional: Configure Hyperledger Explorer for HTTPS
- 11.0 Run Hyperledger Explorer
- 12.0 Optional: Run Hyperledger Explorer Using Docker
- 13.0 NPM Utility Scripts to Dockerize Application
- 14.0 Hyperledger Explorer Swagger
- 15.0 Logs
- 16.0 Troubleshooting
- 17.0 Testing
- 18.0 License
1.0 Release Notes
Hyperledger Explorer Version | Fabric Version Supported | NodeJS Version Supported |
---|---|---|
v1.1.0 (Jul 01, 2020) | v1.4.0 to v2.1.1 | 12.16.x |
v1.0.0 (Apr 09, 2020) | v1.4.0 to v1.4.8 | 10.19.x |
v1.0.0-rc3 (Apr 01, 2020) | v1.4.0 to v1.4.6 | 10.19.x |
v1.0.0-rc2 (Dec 10, 2019) | v1.4.0 to v1.4.4 | 8.11.x |
v1.0.0-rc1 (Nov 18, 2019) | v1.4.2 | 8.11.x |
v0.3.9.5 (Sep 8, 2019) | v1.4.2 | 8.11.x |
v0.3.9.4 (June 18, 2019) | v1.4.1 | 8.11.x |
v0.3.9.3 (May 24, 2019) | v1.4 | 8.11.x |
v0.3.9.2 (May 16, 2019) | v1.4 | 8.11.x |
v0.3.9.1 (Feb 28, 2019) | v1.4 | 8.11.x |
v0.3.9 (Feb 7, 2019) | v1.4 | 8.11.x |
v0.3.8 (Dec 13, 2018) | v1.3 | 8.x.x |
v0.3.7 (Sep 21, 2018) | v1.2 | 8.x.x |
v0.3.6.1 (Sep 21, 2018) | v1.2 | 8.x.x |
v0.3.6 (Sep 6, 2018) | v1.2 | 8.x.x |
v0.3.5.1 (Sep 21, 2018) | v1.1 | 8.x.x |
v0.3.5 (Aug 24, 2018) | v1.1 | 8.x.x |
v0.3.4 (Jul 13, 2018) | v1.1 | 8.x.x |
2.0 Directory Structure
blockchain-explorer | ├── app Application backend root, Explorer configuration | ├── rest REST API | ├── persistence Persistence layer | ├── fabric Persistence API (Hyperledger Fabric) | └── platform Platforms | | └── fabric Explorer API (Hyperledger Fabric) | └── test Application backend test | └── client Web UI ├── public Assets └── src Front end source code ├── components React framework ├── services Request library for API calls ├── state Redux framework └── static Custom and Assets
3.0 Dependencies
Following are the software dependencies required to install and run hyperledger explorer:
- 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
Verified Docker versions supported:
4.0 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
5.0 Database Setup
cd blockchain-explorer/app
- Modify 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/
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:
\l
View created fabricexplorer database.\d
View created tables.
If your Postgresql configured with TLS, read link how to configure connection to Postgresql with TLS
5.1 Authorization Configuration
cd blockchain-explorer/app
- Modify explorerconfig.json to update Authorization (JWT) settings.
"jwt": { "secret" : "a secret phrase!!", "expiresIn": "2 days" }
jwt
:
secret
: secret string to sign the payload.expiresIn
: expressed in seconds or a string describing a time span zeit/ms.Eg:
60
,"2 days"
,"10h"
,"7d"
. A numeric value is interpreted as a seconds count. If you use a string be sure you provide the time units (days, hours, etc), otherwise milliseconds unit is used by default ("120"
is equal to"120ms"
).
6.0 Fabric Network Setup
- Note: This section will take some time to complete.
- Setup your own network using the Building Your First Network tutorial from Hyperledger. Once you setup the network, please modify the values in
/blockchain-explorer/app/platform/fabric/config.json
accordingly. - Hyperledger Explorer defaults to utilize fabric-samples/first-network.
- Make sure to set the environment variables
CORE_PEER_GOSSIP_BOOTSTRAP
andCORE_PEER_GOSSIP_EXTERNALENDPOINT
for each peer in the docker-compose.yaml file. These settings enable the Fabric discovery service, which is used by Hyperledger Explorer to discover the network topology.
6.1 Configure operations service Config-Operations-Service-Hyperledger-Explorer
- Please visit the CONFIG-OPERATIONS-SERVICE-HLEXPLORER.md to configure operations service
7.0 Configure Hyperledger Fabric
On another terminal:
cd blockchain-explorer/app/platform/fabric
- Modify config.json to define your fabric network connection profile:
{ "network-configs": { "first-network": { "name": "firstnetwork", "profile": "./connection-profile/first-network.json", "enableAuthentication": false } }, "license": "Apache-2.0" }
-
"first-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 first-network.json:
- Change "fabric-path" to your fabric network disk path in the first-network.json file:
/blockchain-explorer/app/platform/fabric/connection-profile/first-network.json
- Provide the full disk path to the adminPrivateKey config option, it ussually ends with "_sk", for example:
"/fabric-path/fabric-samples/first-network/crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/aaacd899a6362a5c8cc1e6f86d13bfccc777375365bbda9c710bb7119993d71c_sk"
- "adminUser" is the the admin user of the network, in this case it's fabric CA or an identity user.
- "adminPassword" is the password for the admin user.
- "enableAuthentication" is a flag to enable authentication using a login page, setting to false will skip authentication.
- Change "fabric-path" to your fabric network disk path in the first-network.json file:
7.1 Optional: Configure Fabcar Sample
Setup Fabcar sample network by following Fabcar Sample Network from Hyperledger fabric samples.
- Make sure to set the environment variables
CORE_PEER_GOSSIP_BOOTSTRAP
andCORE_PEER_GOSSIP_EXTERNALENDPOINT
for each peer in the docker-compose.yaml file. These settings enable the Fabric discovery service, which is used by Hyperledger Explorer to discover the network topology. - Configure Fabcar sample network based on this link CONFIG-FABCAR-HLEXPLORER.md
7.2 Optional: Configure Balance Transfer Sample
Balance Transfer Sample network by following Balance Transfer Sample from Hyperledger fabric samples.
- Balance Transfer Sample network based on this link CONFIG-BALANCE-TRANSFER-HLEXPLORER.md
7.3 Optional: Configure for monitoring multiple organizations
You can also configure multiple profiles in config.json
for monitoring multiple organizations in a single Explorer instance. It's quite straightforward. You just need to prepare config.json as below and connection profile for each organization (for example: org1-network.json & org1-network.json). Note that you need to initialize your backend database once when applying v1.0.0-rc3 and above first time in your local environment. Because we've changed database schema in backend database since this version.
{
"network-configs": {
"org1-network": {
"name": "org1-network",
"profile": "./connection-profile/org1-network.json"
},
"org2-network": {
"name": "org2-network",
"profile": "./connection-profile/org2-network.json"
}
},
"license": "Apache-2.0"
}
8.0 Optional: Hyperledger Composer Setup
Setup your own network using Composer Build your network from Hyperledger Composer. Once you setup the network, please modify the values in /blockchain-explorer/app/platform/fabric/config.json
accordingly.
8.1 Optional: Configure Hyperledger Explorer for Composer
On another terminal.
git checkout v0.3.5.1
cd blockchain-explorer/app/platform/fabric
- Modify config.json to update network-config.
- Change "fabric-path" to your composer network path,
- Configure the Hyperledger composer based on this link CONFIG-COMPOSER-HLEXPLORER.md
- Modify "syncStartDate" to filter data by block timestamp
- Modify "channel" to your default channel
If you are connecting to a non TLS fabric peer, please modify "network-id.clients.client-id.tlsEnable" (true->false
) in config.json. Depending on this configuration, the application decides whether to go TLS or non TLS route.
9.0 Optional: Hyperledger Cello Setup
Setup your fabric network using Setup Cello Platform from Hyperledger Cello. Once you setup the network, please modify the values in /blockchain-explorer/app/platform/fabric/config.json
accordingly.
9.1 Optional: Configure Hyperledger Explorer for Cello
On another terminal.
git checkout v0.3.5.1
cd blockchain-explorer/app/platform/fabric
- Modify config.json to update network-config.
- Change "fabric-path" to your cello network path,
- Configure the Hyperledger cello based on this link CONFIG-CELLO-HLEXPLORER.md
- Modify "syncStartDate" to filter data by block timestamp
- Modify "channel" to your default channel
If you are connecting to a non TLS fabric peer, please modify "network-id.clients.client-id.tlsEnable" (true->false
) in config.json. Depending on this configuration, the application decides whether to go TLS or non TLS route.
10.0 Build Hyperledger Explorer
Important: repeat the below steps after every git pull.
On another terminal:
./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
./main.sh test
- to test REST API, and UI components
- to generate code coverage report
Or
cd blockchain-explorer
npm install
cd blockchain-explorer/app/test
npm install
npm run test
cd client/
npm install
npm run test:ci -- -u --coverage
npm run build
10.1 Optional: Configure Hyperledger Explorer for HTTPS
- Configure Hyperledger Explorer for HTTPS based on this link CONFIG-HTTPS-HLEXPLORER.md
11.0 Run Hyperledger Explorer
cd blockchain-explorer/app
- Modify explorerconfig.json to update sync properties
- sync type (local or host), platform, blocksSyncTime(in min) details.
Sync Process Configuration
- Please restart Explorer if any changes made to explorerconfig.json
Host (Standalone)
- Ensure same configuration in Explorer explorerconfig.json if sync process is running from different locations
"sync": {
"type": "host"
}
Local (Run with Explorer)
"sync": {
"type": "local"
}
From a new terminal:
cd blockchain-explorer/
./start.sh
(it will have the backend up)../start.sh debug
(it will have the backend in debug mode)../start.sh print
(it will print help).- Launch the URL http(s)://localhost:8080 on a browser.
./stop.sh
(it will stop the node server).
From new terminal (if Sync Process in Standalone).
-
cd blockchain-explorer/
-
./syncstart.sh
(it will have the sync node up). -
./syncstop.sh
(it will stop the sync node). -
If the Hyperledger Explorer was used previously in your browser be sure to clear the cache before relaunching.
-
If Hyperledger Fabric network is deployed on other machine, please toggle DISCOVERY_AS_LOCALHOST in start.sh / syncstart.sh to 'false'.
11.1 Configuration of logging
By using the following environmet variables, you can control log level of each component (app, db and console). You can set these ALL < TRACE < DEBUG < INFO < WARN < ERROR < FATAL < MARK < OFF
string to each level. Each file is rolled by both date (7days) and size (8MB).
- LOG_LEVEL_APP
- Log level regarding application layer. The logs are written to
logs/app/app.log
. - default
DEBUG
- Log level regarding application layer. The logs are written to
- LOG_LEVEL_DB
- Log level regarding backend layer. The logs are written to
logs/db/db.log
. - default
DEBUG
- Log level regarding backend layer. The logs are written to
- LOG_LEVEL_CONSOLE
- Log level regarding console. The logs are written to
logs/console/console.log
. - default
INFO
- Log level regarding console. The logs are written to
- LOG_CONSOLE_STDOUT
- You can switch the destination of console log from file to standard output.
- default
false
12.0 Optional: Run Hyperledger Explorer Using Docker
There is also an automated deployment of the Hyperledger Explorer available via docker given the following requirements are met:
- BASH installed
- Docker is installed on deployment machine.
- Docker Compose is installed on deployment machine.
12.1 Docker Repository
- Hyperledger Explorer docker repository
https://hub.docker.com/r/hyperledger/explorer/
- Hyperledger Explorer PostgreSQL docker repository
https://hub.docker.com/r/hyperledger/explorer-db
12.2 Run Hyperledger Explorer Using Docker Compose
-
Modify an example of docker-compose.yaml to align with your environment
- networks > mynetwork.com > external > name
networks: mynetwork.com: external: name: net_byfn
- services > explorer.mynetwork.com > volumes
- Connection profile path (ex. ./examples/net1/config.json)
- Connection profile directory path (ex. ./examples/net1/connection-profile, which is referred from config.json)
- Directory path for crypto artifacts of fabric network (ex. ./examples/net1/crypto)
volumes: - ./examples/net1/config.json:/opt/explorer/app/platform/fabric/config.json - ./examples/net1/connection-profile:/opt/explorer/app/platform/fabric/connection-profile - ./examples/net1/crypto:/tmp/crypto
- When you connect the explorer to your fabric network through bridge network, you need to set
DISCOVERY_AS_LOCALHOST
tofalse
for disabling hostname mapping intolocalhost
.
explorer.mynetwork.com: ... environment: ... - DISCOVERY_AS_LOCALHOST=false
-
Run the following to start up explore and explorer-db services after starting your fabric network:
cd /blockchain-explorer docker-compose up -d
-
To stop services without removing persistent data, run the following:
docker-compose down
-
In this 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, run the following:
docker-compose down -v
12.3 Docker Troubleshooting
-
If you have an error on Explorer container as below, the initialisation of database might fail in some reasons.
postgres://hppoc:password@192.168.10.11:5432/fabricexplorer error when connecting to db: { error: role "hppoc" does not exist
In such a case, you need to clear the persistent data by running the following command.
docker-compose down -v docker-compose up -d
-
If you have an error on Explorer container as below, the Explorer might not have connected the network which your fabric network is belonging.
<<<<<<<<<<<<<<<<<<<<<<<<<< Explorer Error >>>>>>>>>>>>>>>>>>>>> Error : [ 'Default client peer is down and no channel details available database' ]
In such a case, you need to check whether the explorer container has belonged to the same network with your fabric network or not, with the following command.
docker network inspect net_byfn | jq ".[].Containers[].Name" | sort "cli" "dev-peer0.org1.example.com-mycc-1.0" "dev-peer0.org2.example.com-mycc-1.0" "dev-peer1.org2.example.com-mycc-1.0" "explorerdb.mynetwork.com" <<--- "explorer.mynetwork.com" <<--- "orderer.example.com" "peer0.org1.example.com" "peer0.org2.example.com" "peer1.org1.example.com" "peer1.org2.example.com"
Or you need to check whether the explorer can ping to each peer on your fabric network or not, with the following command.
docker exec explorer.mynetwork.com ping -c 1 peer0.org1.example.com PING peer0.org1.example.com (172.18.0.3): 56 data bytes 64 bytes from 172.18.0.3: seq=0 ttl=64 time=0.064 ms --- peer0.org1.example.com ping statistics --- 1 packets transmitted, 1 packets received, 0% packet loss round-trip min/avg/max = 0.064/0.064/0.064 ms
13.0 NPM Utility Scripts to Dockerize Application
Set the DOCKER_REGISTRY
variable to the Container Registry you will use and login to that registry if you want to store your container there.
To build the container (auto-tagged as latest
), run:
npm run docker_build
To tag the container with your registry and the NPM package version, run:
npm run docker_tag
To push the container to your registry, run:
npm run docker_push
14.0 Hyperledger Explorer Swagger
- Once the Hyperledger Explorer has been launched go to http://localhost:8080/api-docs to view the Rust API description
- Enter bearer token in Authorize dialog that is generated by the application when you login to Hyperledger Explorer
- Bearer token can be found using Chrome Developer Tools under the Network tab --> Name --> click on REST API request --> Request Headers --> Authorization: bearer
15.0 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. - Logs rotate every 7 days.
16.0 Troubleshooting
- Please visit the TROUBLESHOOT.md to view the Troubleshooting TechNotes for Hyperledger Explorer.
17.0 Testing
-
Unit test
-
End-to-End test
18.0 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/.