everledger / fabkit

Have you always wanted to learn how to use Hyperledger Fabric but never knew how to start?

Meet Fabkit, your Hyperledger Fabric Toolkit to help you dive in 🚀

Prerequisites

The minimum requirements for running Fabkit are simply the following:

• Docker [>= 18.05]
• Docker-compose [>= 1.24]

For Mac and Linux users

If your OS supports bash and you are running this code locally, then beware the following installed version is required

• Bash [>= 4.2]
• zip
• rsync

If you want to be able to use test and build functionalities for your chaincode, depending on the language which it is written in, you may need to install any of the following dependencies:

• Go [>= 1.12]
• Node [>= 10.20]
• Java [>= 8]

For Windows users

Windows users will need to run Fabkit by using the provided Docker image and particularly caring about the syntax when defining the root installation directory.

We recommend to create a directory under your user's home directory, for example, in C:\Users\me\...\fabkit (where C: is the disk used by Windows, me is your current username and ... means "any directory in between").

For instance, you may want to choose to install fabkit in C:\Users\JohnDoe\Workspace\fabkit. In that case, you will need to reformat this directory path as:

//c/Users/JohnDoe/Workspace/fabkit

Then you can replace this string in <FORMATTED_WINDOWS_PATH> and run Fabkit with the below:

docker run --rm -it --name fabkit -e FABKIT_HOST_ROOT=<FORMATTED_WINDOWS_PATH> -v /var/run/docker.sock:/var/run/docker.sock -v <FORMATTED_WINDOWS_PATH>:/home/fabkit everledgerio/fabkit ./fabkit %*

You can put the following in a file called fabkit.bat and include it in your path environment variable to act as an alias.

@echo off
echo.
docker run --rm -it --name fabkit -e FABKIT_HOST_ROOT=<FORMATTED_WINDOWS_PATH> -v /var/run/docker.sock:/var/run/docker.sock -v <FORMATTED_WINDOWS_PATH>:/home/fabkit everledgerio/fabkit ./fabkit %*

Install

You can simply download the install.sh and run it in your terminal with one command:

bash <(curl -sL https://raw.githubusercontent.com/everledger/fabkit/main/install.sh)

or, if you have cloned the repo, you can always run the interactive installer to help you configure fabkit.

./install.sh

Uninstall

To purge fabkit from your system you can run anytime this simply script:

bash <(curl -sL https://raw.githubusercontent.com/everledger/fabkit/main/uninstall.sh)

or directly from this repo with:

./uninstall.sh

Getting started

Before starting the network, let's first install all the required dependencies:

fabkit network install

Run the blockchain network

The following command will spin a Hyperledger Fabric network up, generating channel and crypto config at runtime:

fabkit network start

It will execute the following functions:

• Build and test the chaincode
• Run unit tests
• Generate crypto materials
• Generate genesis block
• Generate default channel configuration files
• Add default peer to join the channel
• Update the channel with anchor peers
• Install the default chaincode into the default peer
• Approve, commit and init the chaincode on the default peer and organization

Afterwards, the network will be ready to accept invoke and query functions.

Run fabkit for the complete list of functionalities and run fabkit <command> help to list it's options.

Run the network with different configurations

You may want to run the network with multiple organizations or by using customized network and channel profiles.

To run the network in multi-org setup, you can use the -o|--orgs <org_no> flag, where org_no is a numeric integer:

fabkit network start --orgs <org_no>

Note: The maximum number of organizations supported at the time of writing is 3.

Or you might want to run a multi-org setup, in debug mode and on a specific version of Fabric:

fabkit network start -o 3 -d -v 2.3.2

For the full list of params, check the helper by typing fabkit network.

Note: Fabkit will save the options of the last deployed network. To redeploy using the same configurations, simply run fabkit network start. To start afresh add the -r option to the command.

Stop a running network

The following command will stop all the components of your running network while preserving all the stored data into the data directory by default:

fabkit network stop

Restart a previously running network

The following command will restart a network with the configuration of your last run only if a data directory is found:

fabkit network restart

Invoke and query

It is possible to use the CLI to run and test functionalities via invoke and query.

Note: The function appearing as a string in the first place of the array Args needs to be defined in the chaincode and the request should be provided as a JSON wrapped into single quotes '.

Invoke

fabkit chaincode invoke [channel_name] [chaincode_name] [org_no] [peer_no] [request]

# e.g.
fabkit chaincode invoke mychannel mygocc 1 0 '{"Args":["put","key1","10"]}'

Query

fabkit chaincode query [channel_name] [chaincode_name] [org_no] [peer_no] [request]

# e.g.
fabkit chaincode query mychannel mygocc 1 0 '{"Args":["get","key1"]}'

Chaincodes

To deep dive in all chaincode operations check out the Working with chaincode section.

Blockchain Explorer

This code is provided with a graphical blockchain explorer powered by Hyperledger Explorer and other useful tools, such as Grafana and Prometheus, in order to have full control over the data stored in your ledger.

Once the configuration is ready, you can run the explorer (and all the connected tools) with a simple command:

fabkit explorer start

To stop and remove all the running Explorer processes:

fabkit explorer stop

UI Explorer

• Username: exploreradmin | Password: exploreradminpw

• Host: http://localhost:8090

Grafana

• Username: admin | Password: admin

• Host: http://localhost:3333

Note: If you are using docker-machine replace localhost with the docker-machine IP address. You can find this out by running docker-machine ip.

Fabric Operations Console (aka IBM Blockchain Platform UI)

Fabric Operations Console provides functionalities to manage Hyperledger Fabric components (peers, CAs, orderers) and perform operations on the network like installing, instantiating, upgrading chaincodes or creating new channels.

To start the console components:

fabkit console start

To stop and remove all console running components:

fabkit console stop

Accessing the console:

• Username: admin | Password: password
• Host: http://localhost:3000

For additional information on how to configure and use the console check the Fabric Operations Console page.

Register and enroll users

Fabkit offers full support to interact with a Fabric CA. To have a complete overview of the all available commands visit the Fabric CA and user certificates management page.

On Ordering service

The consensus mechanism for the Ordering Service so far fully supported by this repo is SOLO, however, there is a 1-org configuration made available for Raft as well and it can be used by replacing the following variable in the .env file:

FABKIT_CONFIGTX_PROFILE_NETWORK=OneOrgOrdererEtcdRaft

Then simply run the network with a single organization:

fabkit network start

All network available configurations can be found under network/config. Users can extend them on their own need.

Benchmarks

Looking for benchmarking your network? Have a look here.

Troubleshooting

If you are experiencing any issue, before opening a ticket, please search among the existing ones or refer to the troubleshooting page.

Contributing (last but not least!)

We, the Fabkit team, are doing our best to put new features on the shelf as soon as they come out and provide the community with a great user experience, however, we are not fulltime dedicated to the job and that is why we need your help!

If you think there are things you will like to see in the next release and you would like to contribute, you are more than welcome!

There are a couple of things you should beware before getting started:

• Check with the team whether this feature has already been / planned to be implemented

• Search if there is any ticket/issue already mentioning the same or similar idea

  • If yes: add your thoughts there

  • If no: open a new ticket and try to be as more descriptive as possible

• Wait for a reply from the team

Do not forget that whatever the outcome of the discussion is going to be, you can always fork this repository and work on your own.

Working on a task

To start working on a feature, you just need to set the FABKIT_ROOT variable to point to your repository directory as it follows:

cd /path/of/this/repo
FABKIT_ROOT="$(pwd)"
alias fabkit="${FABKIT_ROOT}/fabkit"
# if you are using the docker image then set this alias
alias fabkit='docker run -it --rm --name fabkit -e "FABKIT_HOST_ROOT=$FABKIT_ROOT" -v /var/run/docker.sock:/var/run/docker.sock -v "$FABKIT_ROOT":/home/fabkit everledgerio/fabkit:latest ./fabkit "$@"'

Now all the fabkit commands will execute in your repository path.

Once you have done with the changes, simply kill your terminal window. This will reset your FABKIT_ROOT variable to default.