From 0d21b845cc28140de0ea7435276a45eb3570c211 Mon Sep 17 00:00:00 2001 From: Atsushi Neki Date: Mon, 13 Jul 2020 23:09:27 +1000 Subject: [PATCH 1/2] Add another README for detail of each configuration Signed-off-by: Atsushi Neki --- README-CONFIG.md | 269 +++++++++++++++++++++++++++++++++++++++++++++++ README.md | 6 ++ 2 files changed, 275 insertions(+) create mode 100644 README-CONFIG.md diff --git a/README-CONFIG.md b/README-CONFIG.md new file mode 100644 index 000000000..5c6b32570 --- /dev/null +++ b/README-CONFIG.md @@ -0,0 +1,269 @@ + + +## Configuration + +This document will describe about the detail of each configuration: + +## Database + +* 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 configure database settings is to use environment variables, example of settings: + + ```shell + export DATABASE_HOST=127.0.0.1 + export DATABASE_PORT=5432 + export DATABASE_DATABASE=fabricexplorer + export DATABASE_USERNAME=hppoc + export DATABASE_PASSWD=pass12345 + ``` + +## Authorization + +* Modify `app/explorerconfig.json` to update Authorization (JWT) settings. + + ```json + "jwt": { + "secret" : "a secret phrase!!", + "expiresIn": "2 days" + } + ``` + * `secret`: secret string to sign the payload. + * `expiresIn`: expressed in seconds or a string describing a time span [zeit/ms](https://github.com/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"`). + +## Connection profile for Hyperledger Fabric network + +* Modify `app/platform/fabric/config.json` to define your fabric network connection profile: + + ```json + { + "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" + * Change `fabric-path` to your fabric network disk path in the `first-network.json` file + * Provide the full disk path to the adminPrivateKey config option, it ussually ends with "_sk"\ + e.g. + ```json + "adminPrivateKey": { + "path": "/opt/dev/fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/aaacd899a6362a5c8cc1e6f86d13bfccc777375365bbda9c710bb7119993d71c_sk" + }, + ``` + or + Provide the pem string instead. + ```json + "adminPrivateKey": { + "pem": "-----BEGIN PRIVATE KEY-----\nMIGHAgEAMBMG ... utE5HtrGM\n-----END PRIVATE KEY-----\n" + }, + ``` + * `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. + +## Disable Explorer login authentication + +* If you want to disable login authentication, set `false` to `enableAuthentication` in the connection profile + ```json + "client": { + "enableAuthentication": false + } + ``` + +## Using Fabric-CA + +* You need to specify the following keys in the connection profile for using Fabric CA to retrieve certificate: + * client.caCredential + * id + * passowrd + * client.adminCredential + * affiliation + * organizations.[org name] + * certificateAuthorities + + ```json + "client": { + "tlsEnable": true, + "caCredential": { + "id": "admin", + "password": "adminpw" + }, + "adminCredential": { + "id": "exploreradmin", + "password": "exploreradminpw", + "affiliation": "org1.department1" + }, + "enableAuthentication": true, + ``` + ```json + "organizations": { + "org1": { + "mspid": "Org1ExampleCom", + "peers": ["peer0-org1"], + "certificateAuthorities": ["ca0"] + } + }, + ``` + +### Disable using Fabric CA + +* You need to specify the following keys: + * organizations.[org name] + * adminPrivateKey + * signedCert + ```json + "client": { + "tlsEnable": true, + "adminCredential": { + "id": "exploreradmin", + "password": "exploreradminpw", + }, + "enableAuthentication": true, + ``` + ```json + "organizations": { + "org1": { + "mspid": "Org1ExampleCom", + "adminPrivateKey": { + "path": "[path to private key]" + }, + "peers": ["peer0-org1"], + "signedCert": { + "path": "[path to cert]" + } + } + }, + ``` + +## Using client TLS + +* When you set an identity label to `clientTlsIdentity` in the connection profile and store identity, which is correspondent with it, into the wallet (`EXPLORER_ROOTDIR/wallet`), client TLS (mutual TLS) is enabled. + ```json + "client": { + "clientTlsIdentity": "clientTlsId" + } + ``` + + +## Monitoring multiple organizations + +* You can also configure multiple profiles in `app/platform/fabric/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 (e.g. `org1-network.json` & `org2-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. + + ```json + { + "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" + } + ``` + +## Enable HTTPS access to Hyperledger Explorer + +* Configure Hyperledger Explorer for HTTPS based on this link [CONFIG-HTTPS-HLEXPLORER.md](CONFIG-HTTPS-HLEXPLORER.md) + +## Sync process mode + +* Modify `app/explorerconfig.json` to update sync properties +* Please restart Explorer if any changes made to explorerconfig.json +* Ensure same configuration in Explorer explorerconfig.json if sync process is running from different locations + +### Host (Standalone) + +```json +"sync": { + "type": "host", + "platform": "fabric", + "blocksSyncTime": "1" +}, +``` + +### Local (Run with Explorer) + +```json +"sync": { + "type": "local", + "platform": "fabric", + "blocksSyncTime": "1" +}, +``` + +* `sync`: sync type. `local`(run with Explorer) or `host`(standalone) +* `platform`: platform name +* `blocksSyncTime`: sync interval in minute + +## 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_DB + * Log level regarding backend layer. The logs are written to `logs/db/db.log`. + * default `DEBUG` + * LOG_LEVEL_CONSOLE + * Log level regarding console. The logs are written to `logs/console/console.log`. + * default `INFO` + * LOG_CONSOLE_STDOUT + * You can switch the destination of console log from file to standard output. + * default `false` + +## Run Hyperledger Explorer Using Docker Compose + +* Modify an example of `docker-compose.yaml` to align with your environment + * networks > mynetwork.com > external > name + ```yaml + networks: + mynetwork.com: + external: + name: net_byfn + ``` + * services > explorer.mynetwork.com > volumes + * Connection config file 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) + ```yaml + 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` to `false` for disabling hostname mapping into `localhost`. + ```yaml + explorer.mynetwork.com: + ... + environment: + ... + - DISCOVERY_AS_LOCALHOST=false + ``` + * 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: + ```shell + docker-compose down -v + ``` diff --git a/README.md b/README.md index 7dd986314..58b67602a 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ Hyperledger Explorer is a simple, powerful, easy-to-use, well maintained, open s --- 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](README-CONFIG.md). # Quick start (using Docker) @@ -321,6 +322,11 @@ $ npm run build $ DISCOVERY_AS_LOCALHOST=false ./start.sh ``` +# Configuration + +Please refer [README-CONFIG.md](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. From b0c3543fdebe966e3e071a125b4c8ef905790548 Mon Sep 17 00:00:00 2001 From: Atsushi Neki Date: Mon, 13 Jul 2020 23:22:05 +1000 Subject: [PATCH 2/2] Delete old markdown files Signed-off-by: Atsushi Neki --- CONFIG-BALANCE-TRANSFER-HLEXPLORER.md | 39 --------------------------- CONFIG-CELLO-HLEXPLORER.md | 30 --------------------- CONFIG-COMPOSER-HLEXPLORER.md | 24 ----------------- CONFIG-FABCAR-HLEXPLORER.md | 36 ------------------------- 4 files changed, 129 deletions(-) delete mode 100644 CONFIG-BALANCE-TRANSFER-HLEXPLORER.md delete mode 100644 CONFIG-CELLO-HLEXPLORER.md delete mode 100644 CONFIG-COMPOSER-HLEXPLORER.md delete mode 100644 CONFIG-FABCAR-HLEXPLORER.md diff --git a/CONFIG-BALANCE-TRANSFER-HLEXPLORER.md b/CONFIG-BALANCE-TRANSFER-HLEXPLORER.md deleted file mode 100644 index 6069723ec..000000000 --- a/CONFIG-BALANCE-TRANSFER-HLEXPLORER.md +++ /dev/null @@ -1,39 +0,0 @@ - - - -## Configure to Hyperledger Explorer - -Before Configure the Explorer blockchain-explorer/app/platform/fabric/config.json - -- Modify config.json to define you fabric network connection profile - ``` { - "network-configs": { - "balance-transfer": { - "name": "balancetransfer", - "profile": "./connection-profile/balance-transfer.json" - } - }, - "license": "Apache-2.0" - }``` - - - "balance-transfer" is the name of your connection profile, 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 - - Change "fabric-path" to your fabric network path in file /blockchain-explorer/app/platform/fabric/connection-profile/balance-transfer.json, or create another file and specify the path to it, as long as it keeps same format. - - Provide full path to the adminPrivateKey config option, it ussually ends with "_sk", example: - ```"/fabric-path/fabric-samples/balance-transfer/artifacts/channel/crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp/keystore/aaacd899a6362a5c8cc1e6f86d13bfccc777375365bbda9c710bb7119993d71c_sk"``` - - Update all the "fabric-path" accordingly to your balance transfer network location - - "tlsEnable" true|false handles the protocol - - "adminUser" is the the admin user of the network, in this case is fabric CA or an identity user - - "adminPassword" is the password for the admin user. - - "enableAuthentication" true|false, is a flag to enable authentication using a login page, false will skip authentication - -## Run Hyperledger Explorer - -**Code : cd blockchain-explorer/** - -**./start.sh (It will have the backend up)** - -Launch the Hyperledger explorer URL diff --git a/CONFIG-CELLO-HLEXPLORER.md b/CONFIG-CELLO-HLEXPLORER.md deleted file mode 100644 index 62d21dcd0..000000000 --- a/CONFIG-CELLO-HLEXPLORER.md +++ /dev/null @@ -1,30 +0,0 @@ - - - -#Fabric Cluster started using Hyperledger Cello and configure to Explorer - -##Verify docker is running from Master Node - -1. docker -H :2375 info - -##Verify Peer is running and get Ip to configure in explorer from Worker Node - -1. docker ps - -9e807ff75243 hyperledger/fabric-peer:1.1.0 "peer node start" About an hour ago Up About an hour 0.0.0.0:7750->7051/tcp, 0.0.0.0:7650->7053/tcp 5688ceeb13b24e1492b2b2ed676df6e0_peer1_org2 - -ff768afdbe14 hyperledger/fabric-peer:1.1.0 "peer node start" About an hour ago Up About an hour 0.0.0.0:7350->7051/tcp, 0.0.0.0:7250->7053/tcp 5688ceeb13b24e1492b2b2ed676df6e0_peer1_org1 - -bc86570c2b37 hyperledger/fabric-peer:1.1.0 "peer node start" About an hour ago Up About an hour 0.0.0.0:7550->7051/tcp, 0.0.0.0:7450->7053/tcp 5688ceeb13b24e1492b2b2ed676df6e0_peer0_org2 - -c51e6636bb45 hyperledger/fabric-peer:1.1.0 "peer node start" About an hour ago Up About an hour 0.0.0.0:7150->7051/tcp, 0.0.0.0:7050->7053/tcp 5688ceeb13b24e1492b2b2ed676df6e0_peer0_org1 - -ed09a52dba0e hyperledger/fabric-orderer:1.1.0 "orderer" About an hour ago Up About an hour 0.0.0.0:8050->7050/tcp 5688ceeb13b24e1492b2b2ed676df6e0_orderer - -2. docker log c51e6636bb45 ( to verify all peer is up without any error) - -##Hyperledger Explorer configuration - -/app/platform/fabric/config.json (change the configuration , request,event,server-hostname,tls_cacerts,admin(key,value), channelname,mspid,server-hostname,requests,tls_cacerts) - -- Sample configuration provided, see file: blockchain-explorer/app/platform/fabric/config-cello.json. diff --git a/CONFIG-COMPOSER-HLEXPLORER.md b/CONFIG-COMPOSER-HLEXPLORER.md deleted file mode 100644 index 72f395417..000000000 --- a/CONFIG-COMPOSER-HLEXPLORER.md +++ /dev/null @@ -1,24 +0,0 @@ - - - -## Configure to Hyperledger Explorer - -Before Configure the Explorer config.json - -Execute the below command and check peer/orderer is running up or not and verify ip too. - -#### Code : docker ps - -you can open the ~/fabric-tools/DevServer_connectio.json and check , channels , organizations,orderers and peers - -based on that above file configuration we need to configure in Hyperledger Explorer config json ( network-config-name,mspid,peer(requests,events,server-hostname,tls_cacerts),admin(key,cert),channel and orderers(mspid,server_hostname,requests,tls_cacerts). - -- Sample configuration provided, see file: blockchain-explorer/app/platform/fabric/config-composer.json. - -## Run Hyperledger Explorer - -**Code : cd blockchain-explorer/** - -**./start.sh (It will have the backend up)** - -Launch the Hyperledger explorer URL diff --git a/CONFIG-FABCAR-HLEXPLORER.md b/CONFIG-FABCAR-HLEXPLORER.md deleted file mode 100644 index a1012e910..000000000 --- a/CONFIG-FABCAR-HLEXPLORER.md +++ /dev/null @@ -1,36 +0,0 @@ - - - -## Configure to Hyperledger Explorer - -Before Configure the Explorer blockchain-explorer/app/platform/fabric/config.json - -- Modify config.json to define you fabric network connection profile - ``` { - "network-configs": { - "fabcar": { - "name": "fabcar", - "profile": "./connection-profile/fabcar.json" - } - }, - "license": "Apache-2.0" - }``` - - - - "fabcar" is the name of your connection profile, 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" - - "enableAuthentication" option true|false will skipe the login page - -- Modify connection profile - - "adminUser" is the the admin user of the network, in this case is fabric CA or an identity user - - "adminPassword" is the password for the admin user. - - "enableAuthentication" true|false, is a flag to enable authentication using a login page, false will skip authentication - -## Run Hyperledger Explorer - -**Code : cd blockchain-explorer/** - -**./start.sh (It will have the backend up)** - -Launch the Hyperledger explorer URL