From a5e86fde18b70470cb9786d604bf7c1f6c6a30a9 Mon Sep 17 00:00:00 2001 From: Dave Kelsey Date: Mon, 29 Apr 2024 12:34:22 +0100 Subject: [PATCH] Update docs as follows (#1553) - prepare vNext for 0.5.1 release - move all references of fabric to now demonstrate the `fabric-gateway` Signed-off-by: Dave Kelsey --- docs/vNext/CONTRIBUTING.md | 16 +++++------ docs/vNext/Caliper_FAQ.md | 2 +- docs/vNext/Fabric_Configuration_New.md | 18 ++++++++----- docs/vNext/Getting_Started.md | 2 +- docs/vNext/Installing_Caliper.md | 36 ++++++++++++------------- docs/vNext/tutorials_fabric_existing.md | 28 ++++++++++++------- 6 files changed, 59 insertions(+), 43 deletions(-) diff --git a/docs/vNext/CONTRIBUTING.md b/docs/vNext/CONTRIBUTING.md index 1adc00219..b0e05e3eb 100644 --- a/docs/vNext/CONTRIBUTING.md +++ b/docs/vNext/CONTRIBUTING.md @@ -132,14 +132,14 @@ Once Verdaccio is running, you can run the following command to publish every Ca ```console user@ubuntu:~/caliper/packages/caliper-publish$ ./publish.js npm --registry "http://localhost:4873" ... -+ @hyperledger/caliper-core@0.5.0-unstable-20220206065953 -[PUBLISH] Published package @hyperledger/caliper-core@0.5.0-unstable-20220206065953 ++ @hyperledger/caliper-core@0.5.1-unstable-20240422122901 +[PUBLISH] Published package @hyperledger/caliper-core@0.5.1-unstable-20240422122901 ... -+ @hyperledger/caliper-fabric@0.5.0-unstable-20220206065953 -[PUBLISH] Published package @hyperledger/caliper-fabric@0.5.0-unstable-20220206065953 ++ @hyperledger/caliper-fabric@0.5.1-unstable-20240422122901 +[PUBLISH] Published package @hyperledger/caliper-fabric@0.5.1-unstable-20240422122901 ... -+ @hyperledger/caliper-cli@0.5.0-unstable-20220206065953 -[PUBLISH] Published package @hyperledger/caliper-cli@0.5.0-unstable-20200206065953 ++ @hyperledger/caliper-cli@0.5.1-unstable-20240422122901 +[PUBLISH] Published package @hyperledger/caliper-cli@0.5.1-unstable-20240422122901 ``` Take note of the dynamic version number you see in the logs, you will need it to install you modified Caliper version from Verdaccio (the `unstable` tag is also present on NPM, so Verdaccio would probably pull that version instead of your local one). @@ -152,8 +152,8 @@ Once the packages are published to the local Verdaccio server, we can use the us ```console user@ubuntu:~/caliper-benchmarks$ npm install --registry=http://localhost:4873 --only=prod \ - @hyperledger/caliper-cli@0.5.0-unstable-20220206065953 -user@ubuntu:~/caliper-benchmarks$ npx caliper bind --caliper-bind-sut fabric:2.2 + @hyperledger/caliper-cli@0.5.1-unstable-20240422122901 +user@ubuntu:~/caliper-benchmarks$ npx caliper bind --caliper-bind-sut fabric:fabric-gateway user@ubuntu:~/caliper-benchmarks$ npx caliper launch manager \ --caliper-workspace . \ --caliper-benchconfig benchmarks/scenario/simple/config.yaml \ diff --git a/docs/vNext/Caliper_FAQ.md b/docs/vNext/Caliper_FAQ.md index a0d80f970..47c38c959 100644 --- a/docs/vNext/Caliper_FAQ.md +++ b/docs/vNext/Caliper_FAQ.md @@ -41,7 +41,7 @@ The throughput is calculated by `Succ/(last committing time - first submitting t **A:** You first need to deploy that chaincode to your Fabric network, then create your benchmark and workload files see the Caliper Fabric tutorial for further guidance. **Q:** How can I use TLS communication? -**A:** Fabric supports secure communication between nodes and clients using TLS. TLS communication can use both one-way (server only) and two-way (server and client) authentication. You can refer to the [Fabric TLS configuration](https://hyperledger-fabric.readthedocs.io/en/release-2.2/enable_tls.html) page for server side settings. For Caliper-side settings, check the adapter documentation that details how to set the necessary credentials. +**A:** Fabric supports secure communication between nodes and clients using TLS. TLS communication can use both one-way (server only) and two-way (server and client) authentication. You can refer to the [Fabric TLS configuration](https://hyperledger-fabric.readthedocs.io/en/release-2.5/enable_tls.html) page for server side settings. For Caliper-side settings, check the adapter documentation that details how to set the necessary credentials. **Q:** How can I monitor remote Docker containers? **A:** If you need to access the Docker daemon remotely, you need to explicitly enable remote access. Beware that the default setup provides unencrypted and unauthenticated direct access to the Docker daemon. For details, refer to the official [Docker documentation](https://success.docker.com/article/how-do-i-enable-the-remote-api-for-dockerd). diff --git a/docs/vNext/Fabric_Configuration_New.md b/docs/vNext/Fabric_Configuration_New.md index 9c7644c37..e54b6b53f 100644 --- a/docs/vNext/Fabric_Configuration_New.md +++ b/docs/vNext/Fabric_Configuration_New.md @@ -35,24 +35,30 @@ You must bind Caliper to a specific Fabric SDK to target the corresponding (or c > * None of the Fabric bindings support administration actions. It it not possible to create/join channels nor deploy a chaincode. Consequently running caliper only facilitate operations using the `--caliper-flow-only-test` flag -### Binding with Fabric 1.4 +### Binding with Fabric 1.4 Client SDK -It is confirmed that a 1.4 Fabric SDK is compatible with a Fabric 2.2 and later Fabric 2.x SUTs, therefore this binding can be used with later Fabric SUTs +To bind with this client sdk, use `fabric:1.4`. + +It is confirmed that a 1.4 Fabric Client SDK is compatible with a Fabric 2.2 and later Fabric 2.x SUTs, therefore this binding can be used with later Fabric SUTs Note that when using the binding target for the Fabric SDK 1.4 there are capability restrictions: > * Currently setting `discover` to `true` in the network configuration file is not supported if you don't enable the `gateway` option (eg specifying --caliper-Fabric-gateway-enabled as a command line option) > * Detailed execution data for every transaction is only available if you don't enable the `gateway` option -### Binding with Fabric 2.2 +### Binding with Fabric 2.2 Client SDK + +To bind with this client sdk, use `fabric:2.2`. It is confirmed that a 2.2 Fabric SDK is compatible with 2.2 and later Fabric SUTs, therefore this binding can be used with 2.2 and later Fabric SUTs > The following further restrictions exist for this binding > * Detailed execution data for every transaction is not available. -### Binding with Fabric 2.4 +### Binding with Fabric Gateway Client SDK + +To bind with this client sdk, use `fabric:fabric-gateway`. This is now the preferred SDK to use given that Fabric 2.2 and earlier is now not in LTS and as such the Fabric 1.4 and 2.2 SDKs are now deprecated. -Only Fabric 2.4 and later with the Peer Gateway capability enabled (which is the default setting for a Fabric peer) can be used. +Only Fabric 2.4 and later with the Peer Gateway capability enabled (which is the default setting for a Fabric peer) can be used so for older versions of Hyperledger Fabric you cannot bind with this client SDK. > The following further restrictions exist for this binding > * Detailed execution data for every transaction is not available. @@ -430,7 +436,7 @@ Each organization must have `mspid`, `identities` and either `connectionProfle` *
__discover__ _Optional. Boolean._
- A value of `true` indicates that the connection profile is a dynamic connection profile and discovery should be used. If not specified then it defaults to `false`. For a Fabric 1.4 binding you can only set this value to true if you plan to use the `gateway` option + This does not need to be provided when binding to the `fabric-gateway` and will be ignored if provided and is relevant only for the 1.4 and 2.2 fabric bindings. A value of `true` indicates that the connection profile is a dynamic connection profile and discovery should be used. If not specified then it defaults to `false`. For a Fabric 1.4 binding you can only set this value to true if you plan to use the `gateway` option. ```yaml organizations: diff --git a/docs/vNext/Getting_Started.md b/docs/vNext/Getting_Started.md index a26b2bde3..104791342 100644 --- a/docs/vNext/Getting_Started.md +++ b/docs/vNext/Getting_Started.md @@ -44,7 +44,7 @@ Sample benchmarks that may be used by Caliper are hosted on a companion [GitHub Performance reports for the provided samples are hosted on the [documentation pages of the repository](https://hyperledger.github.io/caliper-benchmarks/). -> **Important:** make sure that the version/tag of the benchmark repository matches the version of Caliper you are using! For example, if you are using Caliper v0.5.0, then `checkout` the `v0.5.0` tag after cloning the benchmark repository. The `main` branch of the benchmark repository corresponds to the latest `unstable` Caliper version. +> **Important:** make sure that the version/tag of the benchmark repository matches the version of Caliper you are using! For example, if you are using Caliper v0.5.1, then `checkout` the `v0.5.1` tag after cloning the benchmark repository. The `main` branch of the benchmark repository corresponds to the latest `unstable` Caliper version. ## How to Contribute diff --git a/docs/vNext/Installing_Caliper.md b/docs/vNext/Installing_Caliper.md index 4bc5f81c6..2eed14063 100644 --- a/docs/vNext/Installing_Caliper.md +++ b/docs/vNext/Installing_Caliper.md @@ -47,7 +47,7 @@ The entry point of the CLI is the `caliper` binary. You can confirm whether the ```console user@ubuntu:~/caliper-benchmarks$ npx caliper --version -v0.5.0-unstable-20220324180635 +v0.5.1 ``` The CLI provides multiple commands to perform different tasks. To check the available commands and their descriptions, execute: @@ -88,7 +88,7 @@ To have a look at the help page of the command, execute: ```console user@ubuntu:~/caliper-benchmarks$ npx caliper bind --help Usage: - caliper bind --caliper-bind-sut fabric:2.2 --caliper-bind-cwd ./ --caliper-bind-args="-g" + caliper bind --caliper-bind-sut fabric:fabric-gateway --caliper-bind-cwd ./ --caliper-bind-args="-g" Options: --help, -h Show usage information [boolean] @@ -101,7 +101,7 @@ Options: The binding step technically consists of an extra `npm install` call with the appropriate packages and install settings, fully managed by the CLI. The following parameters can be set for the command: - * __SUT/platform name and SDK version:__ specifies the name of the target platform and its SDK version to install e.g., `fabric:2.2` + * __SUT/platform name and SDK version:__ specifies the name of the target platform and its SDK version to install e.g., `fabric:fabric-gateway` * __Working directory:__ the directory from which the `npm install` command must be performed. Defaults to the current working directory * __User arguments:__ additional arguments to pass to `npm install`, e.g., `--save` @@ -109,7 +109,7 @@ The following SUT name and SDK version combinations are supported: * **besu**: `1.3.2`, `1.3`, `1.4` * **ethereum**: `1.2.1`, `1.3` -* **fabric**: `1.4`, `2.2`, `2.4` +* **fabric**: `1.4`, `2.2`, `fabric-gateway` > __Note:__ Ensure that the SDK you are binding is compatible with the the SUT version that you intend to target. The `bind` command is useful when you plan to run multiple benchmarks against the same SUT version. Bind once, then run different benchmarks without the need to bind again. As you will see in the next sections, the launcher commands for the manager and worker processes can also perform the binding step if the required parameter is present. @@ -240,8 +240,8 @@ But why is all this important to you? Because Caliper is still in its pre-releas Let's see the three types of version numbers you will encounter: * `0.2.0`: Version numbers of this form denote releases deemed _stable_ by the maintainers. Such versions have a corresponding GitHub tag, both in the `caliper` and `caliper-benchmarks` repositories. Moreover, the latest stable version is documented by the matching version of the documentation page. So make sure to align the different versions if you run into some issue. -* `0.5.0-unstable-20220206065953`: Such version "numbers" denote _unstable_ releases that are published upon every merged pull request (hence the timestamp at the end), and eventually will become a stable version, e.g., `0.5.0`. This way you always have access to the NPM (and Docker) artifacts pertaining to the `main` branch of the repository. Let's find and fix the bugs of new features before they make it to the stable release! -* `unstable`: This is the very latest unstable release that has been published and would correspond to a version also published as `0.5.0-unstable-`. This lets you quickly work with the very latest code from the `main` branch. +* `0.5.1-unstable-20240422122901`: Such version "numbers" denote _unstable_ releases that are published upon every merged pull request (hence the timestamp at the end), and eventually will become a stable version, e.g., `0.5.1`. This way you always have access to the NPM (and Docker) artifacts pertaining to the `main` branch of the repository. Let's find and fix the bugs of new features before they make it to the stable release! +* `unstable`: This is the very latest unstable release that has been published and would correspond to a version also published as `0.5.1-unstable-`. This lets you quickly work with the very latest code from the `main` branch. > __Note:__ The newest unstable release always corresponds to the up-to-date version of the related repositories, and the `vNext` version of the documentation page! @@ -258,15 +258,15 @@ The following tools may be required depending on which SUT and version you bind > __Note:__ this is the highly recommended way to install Caliper for your project. Keeping the project dependencies local makes it easier to setup multiple Caliper projects. Global dependencies would require re-binding every time before a new benchmark run (to ensure the correct global dependencies). -1. Install the Caliper CLI as you would any other NPM package. It is highly recommended to explicitly specify the version number, e.g., `@hyperledger/caliper-cli@0.5.0` -2. Bind the CLI to the required platform SDK (e.g., `fabric` with the `2.2` SDK). +1. Install the Caliper CLI as you would any other NPM package. It is highly recommended to explicitly specify the version number, e.g., `@hyperledger/caliper-cli@0.5.1` +2. Bind the CLI to the required platform SDK (e.g., `fabric` with the `fabric-gateway` SDK). 3. Invoke the local CLI binary (using [npx](https://www.npmjs.com/package/npx)) with the appropriate parameters. You can repeat this step for as many benchmarks as you would like. Putting it all together: ```console -user@ubuntu:~/caliper-benchmarks$ npm install --only=prod @hyperledger/caliper-cli@0.5.0 -user@ubuntu:~/caliper-benchmarks$ npx caliper bind --caliper-bind-sut fabric:2.2 +user@ubuntu:~/caliper-benchmarks$ npm install --only=prod @hyperledger/caliper-cli@0.5.1 +user@ubuntu:~/caliper-benchmarks$ npx caliper bind --caliper-bind-sut fabric:fabric-gateway user@ubuntu:~/caliper-benchmarks$ npx caliper launch manager \ --caliper-workspace . \ --caliper-benchconfig benchmarks/scenario/simple/config.yaml \ @@ -276,9 +276,9 @@ user@ubuntu:~/caliper-benchmarks$ npx caliper launch manager \ We could also perform the binding automatically when launching the manager process (note the extra parameter for `caliper launch manager`): ```console -user@ubuntu:~/caliper-benchmarks$ npm install --only=prod @hyperledger/caliper-cli@0.5.0 +user@ubuntu:~/caliper-benchmarks$ npm install --only=prod @hyperledger/caliper-cli@0.5.1 user@ubuntu:~/caliper-benchmarks$ npx caliper launch manager \ - --caliper-bind-sut fabric:2.2 \ + --caliper-bind-sut fabric:fabric-gateway \ --caliper-workspace . \ --caliper-benchconfig benchmarks/scenario/simple/config.yaml \ --caliper-networkconfig networks/fabric/test-network.yaml @@ -300,7 +300,7 @@ There are some minor differences compared to the local install: 4. You can omit the `npx` command, since `caliper` will be in your `PATH`. ```console -user@ubuntu:~$ npm install -g --only=prod @hyperledger/caliper-cli@0.5.0 +user@ubuntu:~$ npm install -g --only=prod @hyperledger/caliper-cli@0.5.1 user@ubuntu:~$ caliper bind --caliper-bind-sut fabric:2.2 --caliper-bind-args=-g user@ubuntu:~$ caliper launch manager \ --caliper-workspace ~/caliper-benchmarks \ @@ -340,17 +340,17 @@ Parts of starting a Caliper container (following the recommendations above): 2. Mount your local working directory to a container directory 3. Set the required binding and run parameters -> __Note:__ the __latest__ (or any other) tag is __not supported__, i.e, you explicitly have to specify the image version you want: `hyperledger/caliper:0.5.0`, similar to the recommended approach for the [NPM packages](#versioning-semantics). +> __Note:__ the __latest__ (or any other) tag is __not supported__, i.e, you explicitly have to specify the image version you want: `hyperledger/caliper:0.5.1`, similar to the recommended approach for the [NPM packages](#versioning-semantics). Putting it all together, split into multiple lines for clarity, and naming the container `caliper`: ```console user@ubuntu:~/caliper-benchmarks$ docker run \ -v $PWD:/hyperledger/caliper/workspace \ - -e CALIPER_BIND_SUT=fabric:2.2 \ + -e CALIPER_BIND_SUT=fabric:fabric-gateway \ -e CALIPER_BENCHCONFIG=benchmarks/scenario/simple/config.yaml \ -e CALIPER_NETWORKCONFIG=networks/fabric/test-network.yaml \ - --name caliper hyperledger/caliper:0.5.0 launch manager + --name caliper hyperledger/caliper:0.5.1 launch manager ``` ### Using docker-compose @@ -363,10 +363,10 @@ version: '2' services: caliper: container_name: caliper - image: hyperledger/caliper:0.5.0 + image: hyperledger/caliper:0.5.1 command: launch manager environment: - - CALIPER_BIND_SUT=fabric:2.2 + - CALIPER_BIND_SUT=fabric:fabric-gateway - CALIPER_BENCHCONFIG=benchmarks/scenario/simple/config.yaml - CALIPER_NETWORKCONFIG=networks/fabric/test-network.yaml volumes: diff --git a/docs/vNext/tutorials_fabric_existing.md b/docs/vNext/tutorials_fabric_existing.md index 3da6380c4..d9dd49804 100644 --- a/docs/vNext/tutorials_fabric_existing.md +++ b/docs/vNext/tutorials_fabric_existing.md @@ -16,16 +16,24 @@ This tutorial takes you through performance testing a smart contract on a pre-ex To complete this tutorial you will need to have installed NodeJS. To do this, we recommend using [nvm](https://github.com/nvm-sh/nvm). -This tutorial is based on resources available from the official [Hyperledger Fabric documentation](https://hyperledger-fabric.readthedocs.io/en/release-2.2/tutorials.html). A network comprised of two organizations and a solo orderer, with the javascript `asset-transfer-basic` smart contract, is assumed to be built and ready to performance test. +This tutorial is based on resources available from the official [Hyperledger Fabric documentation](https://hyperledger-fabric.readthedocs.io/en/release-2.5/tutorials.html). A network comprised of two organizations and a solo orderer, with the javascript `asset-transfer-basic` smart contract (chaincode), is assumed to be built and ready to performance test. > The following command list is a minimalist quick step guide to get the required Fabric network up and running. __We use available Hyperledger Fabric resources at explicit levels. To understand and troubleshoot what occurs during the creation of the test network, please refer to the Fabric documentation linked above!__ +Ensure you have the following pre-reqs installed + +- docker engine or docker desktop +- curl +- jq +- a supported node LTS version. a list current supported LTS versions can be found on the [node.js website](https://nodejs.org/) (to install node easily you can use the nvm tool found [here](https://github.com/nvm-sh/nvm)) + ```bash -# Pull down the 2.2.5 hyperledger fabric images/binaries and the fabric-samples checked out at tag v2.2.5 -curl -sSL https://raw.githubusercontent.com/hyperledger/fabric/main/scripts/bootstrap.sh | bash -s -- 2.2.5 1.5.2 +# Pull down the 2.5.7 hyperledger fabric and 1.5.10 hyperledger fabric ca images/binaries +curl -sSL https://raw.githubusercontent.com/hyperledger/fabric/main/scripts/bootstrap.sh | bash -s -- 2.5.7 1.5.10 cd fabric-samples -# Switch to a release-2.2 git branch that has a fix for asset-transfer-basic chaincode -git checkout c3a0e814f1609eda2b2f4403b38e33b8b4a16675 +# As fabric-samples for hyperledger 2.5 is via the main branch, fix to a specific commit which we know works +# to protect against potential breaking changes in main +git checkout c691cf94a99372e0225927d7927b1bc367018029 # Start up the test-network cd test-network/ ./network.sh up createChannel @@ -37,11 +45,11 @@ Create a folder named **caliper-workspace** at the same level as the **fabric-sa Caliper installation and use will be based on a local npm installation. Within the **caliper-workspace** directory, install caliper CLI using the following terminal command: -`npm install --only=prod @hyperledger/caliper-cli@0.5.0` +`npm install --only=prod @hyperledger/caliper-cli@0.5.1` Bind the SDK using the following terminal command: -`npx caliper bind --caliper-bind-sut fabric:2.2` +`npx caliper bind --caliper-bind-sut fabric:fabric-gateway` Further information relating to the installation and binding of Caliper may be found within the relevant [documentation pages](./Installing_Caliper.md). @@ -119,7 +127,8 @@ organizations: path: '../fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/signcerts/User1@org1.example.com-cert.pem' connectionProfile: path: '../fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/connection-org1.yaml' - discover: true +# Uncomment the next line only if you want to try this network configuration file binding to fabric:2.2, it's not required for fabric-gateway binding +# discover: true ``` Note the `-` sign in front of `mspid` and `name` in the above example. These are important as organizations could contain more than 1 organization. certificates can also contain a list defining more than 1 identity. @@ -165,7 +174,8 @@ organizations: path: '../fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/users/User1@org1.example.com/msp/signcerts/User1@org1.example.com-cert.pem' connectionProfile: path: '../fabric-samples/test-network/organizations/peerOrganizations/org1.example.com/connection-org1.yaml' - discover: true +# Uncomment the next line only if you want to try this network configuration file binding to fabric:2.2, it's not required for fabric-gateway binding +# discover: true ``` ## Step 3 - Build a Test Workload Module