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 π
The minimum requirements for running Fabkit are simply the following:
- Docker [>= 18.05]
- Docker-compose [>= 1.24]
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:
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 %*
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
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
Before starting the network, let's first install all the required dependencies:
fabkit network install
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.
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.
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
The following command will restart a network with the configuration of your last run only if a data directory is found:
fabkit network restart
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 '
.
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"]}'
fabkit chaincode query [channel_name] [chaincode_name] [org_no] [peer_no] [request]
# e.g.
fabkit chaincode query mychannel mygocc 1 0 '{"Args":["get","key1"]}'
To deep dive in all chaincode operations check out the Working with chaincode section.
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
-
Username:
exploreradmin
| Password:exploreradminpw
-
Host: http://localhost:8090
-
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 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.
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.
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.
Looking for benchmarking your network? Have a look here.
If you are experiencing any issue, before opening a ticket, please search among the existing ones or refer to the troubleshooting page.
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.
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.