fablo
Fablo supports:
- Environment: Docker
- RAFT and solo consensus protocols
- Multiple organizations and channels
- Chaincode installation and upgrade
- REST API client for CA and chaincodes (Fablo REST)
- Blockchain Explorer which can be enabled for each organization
See it in action
Installation
Fablo is distributed as a single shell script which uses Docker image to generate the network config.
You may keep the script in the root directory of your project or install it globally in your file system.
To install it globally:
sudo curl -Lf https://github.com/hyperledger-labs/fablo/releases/download/1.1.0/fablo.sh -o /usr/local/bin/fablo && sudo chmod +x /usr/local/bin/fablo
To get a copy of Fablo for a single project, execute in the project root:
curl -Lf https://github.com/hyperledger-labs/fablo/releases/download/1.1.0/fablo.sh -o ./fablo && chmod +x ./fablo
Getting started
To create a local Hyperledger Fabric network with Node.js chaincode and REST API client, install Fablo and execute:
./fablo init node rest ./fablo up
After a few minutes the whole network will be set up and running.
You can check the running nodes via docker ps
or docker stats
, and you can query the network with command line (via cli.org1.example.com
container) or REST API client (via Fablo REST).
Basic usage
fablo up /path/to/fablo-config.json
The up
command creates initial configuration and starts Hyperledger Fabric network on Docker.
In this case network configuration is saved in $(pwd)/fablo-target
.
Then you can manage the network with other commands, for example stop
, start
, down
, prune
.
Provided Fablo configuration file describes network topology: root organization, other organizations, channels and chaincodes.
See the samples or Fablo config section.
There are two basic use cases.
You may use Fablo to start and manage the network for development purposes, test different network topologies, run it in CI environment etc.
In this case you should keep fablo-target
directory intact and out of the version control.
Fablo will manage it locally.
On the other hand you can use Fablo to generate initial network configuration, keep it in version control and tweak for specific requirements.
In this case, however, you should use generated fablo-docker.sh
instead of fablo
script.
Managing the network
init
fablo init [node] [rest] [dev]
Creates simple network config file in current dir.
Good step to start your adventure with Fablo or set up a fast prototype.
Fablo init
command takes three parameters (the order does not matter):
-
Option
node
makes Fablo to generate a sample Node.js chaincode as well. -
Option
rest
enables simple REST API with Fablo REST as standalone Docker container. -
Option
dev
enables running peers in dev mode (so the hot reload for chaincode is possible).
Sample command:
fablo init node dev
Generated fablo-config.json
file uses single node Solo consensus and no TLS support.
This is the simplest way to start with Hyperledger Fabric, since Raft consensus requires TLS and TLS itself adds a lot of complexity to the blockchain network and integration with it.
generate
fablo generate [/path/to/fablo-config.json|yaml [/path/to/fablo/target]]
Generates network configuration files in the given directory.
Default config file path is $(pwd)/fablo-config.json
or $(pwd)/fablo-config.yaml
, default directory is $(pwd)/fablo-target
.
If you specify a different directory, you loose Fablo support for other commands.
If you want to use Fablo only to kick off the Hyperledger Fabric network, you may provide target directory parameter or just copy generated Fablo target directory content to desired directory and add it to version control.
Note that generated files may contain variables with paths on your disk and generated crypto material for Hyperledger Fabric.
Review the files before submitting to version control system.
up
fablo up [/path/to/fablo-config.json|yaml]
Starts the Hyperledger Fabric network for given Fablo configuration file, creates channels, installs and instantiates chaincodes.
If there is no configuration, it will call generate
command for given config file.
down, start, stop
fablo [down | start | stop]
Downs, starts or stops the Hyperledger Fabric network for configuration in the current directory.
This is similar to down, start and stop commands for Docker Compose.
prune
fablo prune
Downs the network and removes fablo-target
directory.
reset and recreate
fablo reset fablo recreate [/path/to/fablo-config.json|yaml]
-
reset
— down and up steps combined. Network state is lost, but the configuration is kept intact. Useful in cases when you want a fresh instance of network without any state. -
recreate
— prunes the network, generates new config files and ups the network. Useful when you editedfablo-config
file and want to start newer network version in one command.
validate
fablo validate [/path/to/fablo-config.json|yaml]
Validates network config. This command will validate your network config try to suggest necessary changes or additional tweaks.
Please note that this step is also executed automatically before each generate
to ensure that at least critical errors where fixed.
snapshot and restore
Fablo supports saving state snapshot (backup) of the network and restoring it.
It saves all network artifacts, certificates, and the data of CA, orderer and peer nodes.
Note the snapshot does not contain Fablo config file and chaincode source code, since both can be located outside Fablo working directory.
Snapshotting might be useful if you want to keep the current state of a network for future use (for testing, sharing the network state, courses and so on).
fablo snapshot <target-snapshot-path>
If you want to restore snapshot into current directory, execute:
fablo restore <source-snapshot-path>
Example:
- Assume you have a working network with some state.
-
Execute
./fablo snapshot /tmp/my-snapshot
. It will create a file/tmp/my-snapshot.fablo.tar.gz
with the state of the network. It is not required to stop the network before making a snapshot. -
Execute
./fablo prune
to destroy the current network. If the network was present, Fablo would not be able to restore the new one from backup. -
Execute
./fablo restore /tmp/my-snapshot
to restore the network. -
Execute
./fablo start
to start the restored network.
Typically, a snapshot of the network with little data will take less than 1 MB, so it is easy to share.
fabric-docker.sh
The script fabric-docker.sh
is generated among docker network configuration.
It does not support generate
command, however other commands work in same way as in fablo
.
Basically fablo
forwards some commands to this script.
If you want to use Fablo for network configuration setup only, then the fabric-docker.sh
file allows you to manage the network.
Managing chaincodes
chaincode(s) install
fablo chaincodes install
Install all chaincodes. Might be useful if for some reason, Fablo won’t manage to do it by itself.
If you want to install a single chaincode defined in Fablo config file, execute:
fablo chaincode install <chaincode-name> <version>
chaincode upgrade
fablo chaincode upgrade <chaincode-name> <version>
Upgrades chaincode with given name on all relevant peers.
Chaincode directory is specified in Fablo config file.
Running chaincodes in dev mode
Hyperledger Fabric allows to run peers in dev mode in order to allow simple develop of chaincodes.
In this case chaincodes do not need to be upgraded each time, but they are run locally.
This feature allows hot reload of chaincode code and speeds up the development a lot.
Fablo will run peers in dev mode when global.peerDevMode
is set to true
.
Note: in this case TLS has to be disabled, otherwise config validation fails.
The simplest way of trying Fablo with dev mode is as follows:
-
Execute
fablo init node dev
.
It will initialize Fablo config file with sample node chaincode and dev mode enabled.
In this case Fablo config file hasglobal.peerDevMode
set totrue
, and thepackage.json
file for sample Node.js…