Setting up the development environment¶
Ensure you install
2.5 of softhsm, if you are using a distribution package manager such as
apt on ubuntu
or Homebrew on Mac OS, make sure that it offers this version otherwise you will need to install from source. Version 2.6
of SoftHSM is known to have problems. Older versions than 2.5 may work however.
When installing SoftHSM, you should note the path where the shared library
libsofthsm2.so is installed
you may need to have to provide this later in an environment variable to get the PKCS11 tests to pass.
Install the Prerequisites using Homebrew on MacOS¶
For macOS, Homebrew can be used to manage the development prereqs (assuming that you would like to install the latest versions). 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, for example:
brew install git jq brew install --cask docker
Go and SoftHSM are akso available from Homebrew but make sure you install the appropriate versions
Docker Desktop must be launched to complete the installation so be sure to open 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
command to succeed you will still need to have the
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
curl command that comes with Git and Docker Toolbox is old and
does not handle properly the redirect used in
Getting Started - Install. Make sure you have and use a newer version
which can be downloaded from the cURL downloads page
Clone the Hyperledger Fabric source¶
First navigate to https://github.com/hyperledger/fabric and fork the fabric repository using the fork button in the top-right corner. After forking, clone the repository.
mkdir -p github.com/<your_github_userid> cd github.com/<your_github_userid> git clone https://github.com/<your_github_userid>/fabric
If you are running Windows, before cloning the repository, run the following command:
git config --get core.autocrlf
core.autocrlf is set to
true, you must set it to
git config --global core.autocrlf false
A PKCS #11 cryptographic token implementation is required to run the unit tests. The PKCS #11 API is used by the bccsp component of Fabric to interact with hardware security modules (HSMs) that store cryptographic information and perform cryptographic computations. For test environments, SoftHSM can be used to satisfy this requirement.
SoftHSM generally requires additional configuration before it can be used. For example, the default configuration will attempt to store token data in a system directory that unprivileged users are unable to write to.
SoftHSM configuration typically involves copying
/usr/local/etc/softhsm/softhsm2.conf for macOS) to
$HOME/.config/softhsm2/softhsm2.conf and changing
to an appropriate location. Please see the man page for
After SoftHSM has been configured, the following command can be used to initialize the token required by the unit tests:
softhsm2-util --init-token --slot 0 --label ForFabric --so-pin 1234 --pin 98765432
If tests are unable to locate the libsofthsm2.so library in your environment, specify the library path, the PIN, and the label of your token in the appropriate environment variables. For example, on macOS, depending on where the library has been installed:
export PKCS11_LIB="/usr/local/Cellar/softhsm/2.6.1/lib/softhsm/libsofthsm2.so" export PKCS11_PIN=98765432 export PKCS11_LABEL="ForFabric"
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
The OpenSC Project provides a shared
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
the PKCS #11 library and set the
PKCS11SPY environment variable to the real
library. For example:
export PKCS11_LIB="/usr/lib/softhsm/libsofthsm2.so" export PKCS11SPY="/usr/lib/x86_64-linux-gnu/pkcs11/pkcs11-spy.so"
Install the development tools¶
Once the repository is cloned, you can use
make to install some of the
tools used in the development environment. By default, these tools will be
$HOME/go/bin. Please be sure your
PATH includes that
After installing the tools, the build environment can be verified by running a few commands.
make basic-checks integration-test-prereqs ginkgo -r ./integration/nwo
If those commands completely successfully, you’re ready to Go!