Skip to content

Commit

Permalink
Address windows platform in documentation
Browse files Browse the repository at this point in the history 
closes #2993
Signed-off-by: D <[email protected]>
(cherry picked from commit e7ebce1)

# Conflicts:
#	docs/source/dev-setup/devenv.rst
#	docs/source/install.md
#	docs/source/prereqs.md
  • Loading branch information
D authored and mergify-bot committed Jan 27, 2022
1 parent 3c22d41 commit a1525ad
Show file tree
Hide file tree
Showing 4 changed files with 359 additions and 44 deletions.
103 changes: 60 additions & 43 deletions docs/source/dev-setup/devenv.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,25 @@ Setting up the development environment
Prerequisites
~~~~~~~~~~~~~

<<<<<<< HEAD
- `Git client <https://git-scm.com/downloads>`__
- `Go <https://golang.org/dl/>`__ version 1.15.x
- `Docker <https://docs.docker.com/get-docker/>`__ version 18.03 or later
- (macOS) `Xcode Command Line Tools <https://developer.apple.com/downloads/>`__
- `SoftHSM <https://github.com/opendnssec/SoftHSMv2>`__
- `jq <https://stedolan.github.io/jq/download/>`__
=======
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 <https://developer.apple.com/downloads/>`__
- (All platforms) `SoftHSM <https://github.com/opendnssec/SoftHSMv2>`__ use version 2.5 as 2.6 is not operable in this environment
- (All platforms) `jq <https://stedolan.github.io/jq/download/>`__

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
~~~~~
Expand All @@ -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:

::
Expand All @@ -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
<https://curl.haxx.se/download.html>`__
It is recommended that all development be done within your WSL2 Linux distribution.

Clone the Hyperledger Fabric source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Expand All @@ -80,21 +73,6 @@ the repository.
cd github.com/<your_github_userid>
git clone https://github.com/<your_github_userid>/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
^^^^^^^^^^^^^^^^^
Expand Down Expand Up @@ -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 <https://github.com/OpenSC/OpenSC>`__ 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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Expand Down
80 changes: 80 additions & 0 deletions docs/source/install.md
View file
Original file line number Diff line number Diff line change
@@ -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`,<br>
* `configtxlator`,<br>
* `cryptogen`,<br>
* `discover`,<br>
* `idemixgen`,<br>
* `orderer`,<br>
* `osnadmin`,<br>
* `peer`,<br>
* `fabric-ca-client`,<br>
* `fabric-ca-server`<br>


## Download Fabric samples, docker images, and binaries.

Download `fabric-samples` to the `$HOME/go/src/github.com/<your_github_userid>` 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/<your_github_userid>
$ cd $HOME/go/src/github.com/<your_github_userid>
```

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 -- <fabric_version> <fabric-ca_version>
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/<user-defined-workspace>/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).

<!--- Licensed under Creative Commons Attribution 4.0 International License
https://creativecommons.org/licenses/by/4.0/ -->
Loading

0 comments on commit a1525ad

Please sign in to comment.