From a1525ad33c2839229e968528ed34c632f97d9eb5 Mon Sep 17 00:00:00 2001 From: D Date: Mon, 24 Jan 2022 17:19:10 +0000 Subject: [PATCH] Address windows platform in documentation closes #2993 Signed-off-by: D (cherry picked from commit e7ebce15bb449c3fad68050a4888b7038fbec3db) # Conflicts: # docs/source/dev-setup/devenv.rst # docs/source/install.md # docs/source/prereqs.md --- docs/source/dev-setup/devenv.rst | 103 ++++++----- docs/source/install.md | 80 +++++++++ docs/source/prereqs.md | 218 +++++++++++++++++++++++ docs/source/tutorial/commercial_paper.md | 2 +- 4 files changed, 359 insertions(+), 44 deletions(-) create mode 100644 docs/source/install.md create mode 100644 docs/source/prereqs.md diff --git a/docs/source/dev-setup/devenv.rst b/docs/source/dev-setup/devenv.rst index 7f3b2b759ce..5f64e1e30f2 100644 --- a/docs/source/dev-setup/devenv.rst +++ b/docs/source/dev-setup/devenv.rst @@ -4,13 +4,25 @@ Setting up the development environment Prerequisites ~~~~~~~~~~~~~ +<<<<<<< HEAD - `Git client `__ - `Go `__ version 1.15.x - `Docker `__ version 18.03 or later - (macOS) `Xcode Command Line Tools `__ - `SoftHSM `__ - `jq `__ +======= +In addition to the standard :doc:`../prereqs` for Fabric, the following prerequisites are also required: +>>>>>>> e7ebce15b (Address windows platform in documentation) +- (macOS) `Xcode Command Line Tools `__ +- (All platforms) `SoftHSM `__ use version 2.5 as 2.6 is not operable in this environment +- (All platforms) `jq `__ + +For Linux platforms, including WSL2 on Windows, also required are various build tools such as gnu-make and +C compiler. On ubuntu and it's derivatives you can install the required toolset by using the command +``sudo apt install build-essential``. Other distributions may already have the appropriate tools installed +or provide a convenient way to install the various build tools. Steps ~~~~~ @@ -26,10 +38,17 @@ Once Homebrew is ready, installing the necessary prerequisites is very easy: :: +<<<<<<< HEAD brew install git go jq softhsm brew cask install --appdir="/Applications" docker +======= + brew install git jq + brew install --cask docker + +Go and SoftHSM are also available from Homebrew, but make sure you install the appropriate versions +>>>>>>> e7ebce15b (Address windows platform in documentation) -Docker Desktop must be launched to complete the installation so be sure to open +Docker Desktop must be launched to complete the installation, so be sure to open the application after installing it: :: @@ -39,33 +58,7 @@ the application after installing it: Developing on Windows ~~~~~~~~~~~~~~~~~~~~~ -On Windows 10 you should use the native Docker distribution and you -may use the Windows PowerShell. However, for the ``binaries`` -command to succeed you will still need to have the ``uname`` command -available. You can get it as part of Git but beware that only the -64bit version is supported. - -Before running any ``git clone`` commands, run the following commands: - -:: - - git config --global core.autocrlf false - git config --global core.longpaths true - -You can check the setting of these parameters with the following commands: - -:: - - git config --get core.autocrlf - git config --get core.longpaths - -These need to be ``false`` and ``true`` respectively. - -The ``curl`` command that comes with Git and Docker Toolbox is old and -does not handle properly the redirect used in -:doc:`../getting_started`. Make sure you have and use a newer version -which can be downloaded from the `cURL downloads page -`__ +It is recommended that all development be done within your WSL2 Linux distribution. Clone the Hyperledger Fabric source ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -80,21 +73,6 @@ the repository. cd github.com/ git clone https://github.com//fabric -.. note:: - If you are running Windows, before cloning the repository, run the following - command: - - :: - - git config --get core.autocrlf - - If ``core.autocrlf`` is set to ``true``, you must set it to ``false`` by - running: - - :: - - git config --global core.autocrlf false - Configure SoftHSM ^^^^^^^^^^^^^^^^^ @@ -131,6 +109,45 @@ appropriate environment variables. For example, on macOS: export PKCS11_PIN=98765432 export PKCS11_LABEL="ForFabric" +<<<<<<< HEAD +======= +If you installed SoftHSM on ubuntu from source then the environment variables may look like + +:: + + export PKCS11_LIB="/usr/local/lib/softhsm/libsofthsm2.so" + export PKCS11_PIN=98765432 + export PKCS11_LABEL="ForFabric" + + +The tests don't always clean up after themselves and, over time, this causes +the PKCS #11 tests to take a long time to run. The easiest way to recover from +this is to delete and recreate the token. + +:: + + softhsm2-util --delete-token --token ForFabric + softhsm2-util --init-token --slot 0 --label ForFabric --so-pin 1234 --pin 98765432 + +Debugging with ``pkcs11-spy`` +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The `OpenSC Project `__ provides a shared +library called ``pkcs11-spy`` that logs all interactions between an application +and a PKCS #11 module. This library can be very useful when troubleshooting +interactions with a cryptographic token device or service. + +Once the library has been installed, configure Fabric to use ``pkcs11-spy`` as +the PKCS #11 library and set the ``PKCS11SPY`` environment variable to the real +library. For example: + +:: + + export PKCS11SPY="/usr/lib/softhsm/libsofthsm2.so" + export PKCS11_LIB="/usr/lib/x86_64-linux-gnu/pkcs11/pkcs11-spy.so" + + +>>>>>>> e7ebce15b (Address windows platform in documentation) Install the development tools ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/source/install.md b/docs/source/install.md new file mode 100644 index 00000000000..b5230e456d3 --- /dev/null +++ b/docs/source/install.md @@ -0,0 +1,80 @@ +# Install Fabric and Fabric Samples + +Please install the [Prerequisites](./prereqs.html) before following these install instructions. + +We think the best way to understand something is to use it yourself.  To help you use Fabric, we have created a simple Fabric test network using docker compose, and a set of sample applications that demonstrate its core capabilities. +We have also precompiled `Fabric CLI tool binaries` and `Fabric Docker Images` which will be downloaded to your environment, to get you going. + +The cURL command in the instructions below sets up your environment so that you can run the Fabric test network. Specifically, it performs the following steps: +* Clones the [hyperledger/fabric-samples](https://github.com/hyperledger/fabric-samples) repository. +* Downloads the latest Hyperledger Fabric Docker images and tags them as `latest` +* Downloads the following platform-specific Hyperledger Fabric CLI tool binaries and config files into the `fabric-samples` `/bin` and `/config` directories. These binaries will help you interact with the test network. + * `configtxgen`,
+ * `configtxlator`,
+ * `cryptogen`,
+ * `discover`,
+ * `idemixgen`,
+ * `orderer`,
+ * `osnadmin`,
+ * `peer`,
+ * `fabric-ca-client`,
+ * `fabric-ca-server`
+ + +## Download Fabric samples, docker images, and binaries. + +Download `fabric-samples` to the `$HOME/go/src/github.com/` directory.  This is a Golang Community recommendation for Go projects. If you are using a different directory or Windows, see the [Notes](https://hyperledger-fabric.readthedocs.io/en/latest/install.html#notes) below. + +```shell +$ mkdir -p $HOME/go/src/github.com/ +$ cd $HOME/go/src/github.com/ +``` + +Download the latest release of Fabric samples, docker images, and binaries. + +```shell +$ curl -sSL https://bit.ly/2ysbOFE | bash -s +``` + +You have completed installing Fabric samples, docker images, and binaries to your system. + +## Advanced download options + +To view the help and available commands for the download script, please use the `-h` flag with the cURL command: + +```shell +curl -sSL https://bit.ly/2ysbOFE | bash -s -- -h +``` + +To download a specific release, pass a version identifier for Fabric and Fabric CA Docker images. The command below demonstrates how to download the latest production releases - `Fabric v2.4.1` and `Fabric CA v1.5.2`  + +```shell +curl -sSL https://bit.ly/2ysbOFE | bash -s -- +curl -sSL https://bit.ly/2ysbOFE | bash -s -- 2.4.1 1.5.2 +``` + +## Notes + +### Other considerations + +* Setting GOPATH is not required when using Go modules in your projects, or when using the recommended directory. If you would like to use a different location for fabric-samples, you may set GOPATH to point to your specific Go workspace. For example on macOS: + + ```shell + $ export GOPATH:$Home//go + ``` + +* If you are looking to set up your environment to start contributing to Fabric, please refer to the instructions for [Setting up the contributor development environment](https://hyperledger-fabric.readthedocs.io/en/latest/dev-setup/devenv.html). + +## Troubleshooting + +* If you get an error running the cURL command + * You may have too old a version of cURL that does not handle redirects or an unsupported environment. Please make sure you use a newer version from the [cURL downloads page](https://curl.haxx.se/download.html) + * Alternately, there might be an issue with the bit.ly, please retry the command with the un-shortened URL: + ```shell + curl -sSL https://raw.githubusercontent.com/hyperledger/fabric/main/scripts/bootstrap.sh| bash -s  + ``` + +* If you need help, post your questions and share your logs on the **fabric-questions** channel on [Hyperledger Rocket Chat](https://chat.hyperledger.org/home) or on [StackOverflow](https://stackoverflow.com/questions/tagged/hyperledger-fabric). + + diff --git a/docs/source/prereqs.md b/docs/source/prereqs.md new file mode 100644 index 00000000000..cdf91ba967c --- /dev/null +++ b/docs/source/prereqs.md @@ -0,0 +1,218 @@ +# Prerequisites + +The following prerequisites are required to run a Docker-based Fabric test network on your local machine. + +## Mac + + +
+ +### Homebrew + +For macOS, we recommend using [Homebrew](https://brew.sh) to manage the prereqs. + +```shell +$ /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)" +$ brew --version +Homebrew 2.5.2 +``` + +The Xcode command line tools will be installed as part of the Homebrew installation. +Once Homebrew is ready, installing the necessary prerequisites is very easy: + +### Git + +Install the latest version of [git](https://git-scm.com/downloads) if it is not already installed. + +```shell +$ brew install git +$ git --version +git version 2.23.0 +``` + +### cURL + +Install the latest version of [cURL](https://curl.haxx.se/download.html) if it is not already installed. + +```shell +$ brew install curl +$ curl --version +curl 7.64.1 (x86_64-apple-darwin19.0) libcurl/7.64.1 (SecureTransport) LibreSSL/2.8.3 zlib/1.2.11 nghttp2/1.39.2 +Release-Date: 2019-03-27 +``` + +### Docker + +Install the latest version of [Docker Desktop](https://docs.docker.com/get-docker/) if it is not already installed. +Since Docker Desktop is a UI application on Mac, use `cask` to install it. + +Homebrew v2.x: + +```shell +$ brew cask install --appdir="/Applications" docker +``` + +Homebrew v3.x: + +```shell +$ brew install --cask --appdir="/Applications" docker +``` + +Docker Desktop must be launched to complete the installation so be sure to open the application after installing it: + +```shell +$ open /Applications/Docker.app +``` + +Once installed, confirm the latest versions of both `docker` and `docker-compose` executables were installed. + +```shell +$ docker --version +Docker version 19.03.12, build 48a66213fe +$ docker-compose --version +docker-compose version 1.27.2, build 18f557f9 +``` + +> **Note:** Some users have reported errors while running Fabric-Samples with the Docker Desktop `gRPC FUSE for file sharing` option checked. +> Please uncheck this option in your Docker Preferences to continue using `osxfs for file sharing`. + +### Go + +Optional: Install the latest Fabric supported version of [Go](https://golang.org/doc/install) if it is not already +installed (only required if you will be writing Go chaincode or SDK applications). + +```shell +$ brew install go@1.17.5 +$ go version +go1.17.5 darwin/amd64 +``` + +### JQ + +Optional: Install the latest version of [jq](https://stedolan.github.io/jq/download/) if it is not already installed +(only required for the tutorials related to channel configuration transactions). + +```shell +$ brew install jq +$ jq --version +jq-1.6 +``` +
+ +## **Linux** + + +
+ +### Git + +Install the latest version of [git](https://git-scm.com/downloads) if it is not already installed. + +```shell +$ sudo apt-get install git +``` + +### cURL + +Install the latest version of [cURL](https://curl.haxx.se/download.html) if it is not already installed. + +```shell +$ sudo apt-get install curl +``` + +### Docker + +Install the latest version of [Docker](https://docs.docker.com/get-docker/) if it is not already installed.  + +```shell +sudo apt-get -y install docker-compose +``` + +Once installed, confirm that the latest versions of both Docker and Docker Compose executables were installed. + +```shell +$ docker --version +Docker version 19.03.12, build 48a66213fe +$ docker-compose --version +docker-compose version 1.27.2, build 18f557f9 +``` + +Make sure the Docker daemon is running. + +```shell +sudo systemctl start docker +``` + +Optional: If you want the Docker daemon to start when the system starts, use the following: + +```shell +sudo systemctl enable docker +``` + +Add your user to the Docker group. + +```shell +sudo usermod -a -G docker +``` + +### Go + +Optional: Install the latest version of [Go](https://golang.org/doc/install) if it is not already installed +(only required if you will be writing Go chaincode or SDK applications). + +### JQ + +Optional: Install the latest version of [jq](https://stedolan.github.io/jq/download/) if it is not already installed +(only required for the tutorials related to channel configuration transactions). + +
+ +## **Windows** + + +
+ +### Docker + +Install the latest version of [Docker Desktop](https://docs.docker.com/get-docker/) if it is not already installed. + +### WSL2 + +Both the Fabric documentation and Fabric samples rely heavily on a `bash` environment. The recommended +path is to use WSL2 (Windows Subsystem for Linux version 2) to provide a native Linux environment and then you can follow the Linux prerequisites section (excluding the Linux Docker prerequisite as you already have Docker Desktop) and install them into your WSL2 linux distribution. + +WSL2 may not be installed by default; you can check and install WSL2 by going into "Programs and Features", clicking on "Turn Windows features on or off" and ensuring that both "Windows Subsystem For Linux" and "Virtual Machine Platform" are selected. + +Next you will need to install a Linux distribution such as Ubuntu-20.04 and make sure it's set to using version 2 of WSL. Refer to [Install WSL](https://docs.microsoft.com/en-us/windows/wsl/install) for more information. + +Finally, you need to ensure Docker Desktop has integration enabled for your distribution so it can interact with Docker elements, such as a bash command window. To do this, open the Docker Desktop gui and go into settings, select `Resources` and them `WSL Integration` and ensure the checkbox for enable integration is checked. You should then see your WSL2 linux distribution listed (if you don't then it is probably because it is still a WSL1 distribution and needs to be converted to WSL2) and you can then toggle the switch to enable integration for that distro. Refer to [Docker Desktop WSL2 backend](https://docs.docker.com/desktop/windows/wsl/) for more information + +### Microsoft VS Code (Optional) + +Microsoft VS Code provides an IDE that has tight integration with WSL2 Linux Distibutions. Search the Microsoft Marketplace in VS Code for the Remote Development extension pack for more information. This pack includes, among other things, the `Remote - WSL extension` and the `Remote - Containers` extension. + +### Git For Windows (Optional) + +Although not required, if you do decide to install Git on Windows and manage the Fabric repositories natively (as opposed to within WSL2 and its Git installation), then make sure you configure Git as follows: + +Update the following `git` configurations: +```shell +git config --global core.autocrlf false +git config --global core.longpaths true +``` + +You can check the setting of these parameters with the following commands: +```shell +git config --get core.autocrlf +git config --get core.longpaths +``` +These output from these commands should be false and true respectively. + +
+ +## **Notes** + +- These prerequisites are recommended for Fabric users. If you are a Fabric developer, please refer to the instructions for [Setting up the development environment](https://hyperledger-fabric.readthedocs.io/en/latest/dev-setup/devenv.html). + + diff --git a/docs/source/tutorial/commercial_paper.md b/docs/source/tutorial/commercial_paper.md index d81fe0d8757..96be493ef16 100644 --- a/docs/source/tutorial/commercial_paper.md +++ b/docs/source/tutorial/commercial_paper.md @@ -39,7 +39,7 @@ network. [buy](#buy-application) and [redeem](#redeem-application) commercial paper This tutorial has been tested on MacOS and Ubuntu, and should work on other -Linux distributions. A Windows version is under development. +Linux distributions. ## Prerequisites