Fablo

<h1><img src="./logo.svg" alt="Fablo"/></h1>

Fablo allows you to start Hyperledger Fabric network from a single config file. It's best for local development, CI processes and experimenting with various network configurations.

Fablo supports:

• Environment: Docker
• RAFT, solo and BFT consensus protocols
• Multiple organizations and channels
• Chaincode installation and upgrade (Node, Go, Java, CCaaS)
• REST API client for CA and chaincodes (Fablo REST)
• Blockchain Explorer which can be enabled for each organization

Visit SUPPORTED_FEATURES.md to see the full list of features supported by Fablo.

See it in action

>>> Watch the demo <<<

Quick start

curl fablo.io/install.sh | bash
./fablo init node rest
./fablo up

This will create a local Hyperledger Fabric network with a sample Node.js chaincode (using the node parameter) and a REST API client (using the rest parameter). After a few minutes, the entire network will be set up and running.

You can check the running nodes using docker ps or docker stats. You can also query the network via the command line (fablo chaincode invoke or fablo chaincode query), use the REST API client (see Fablo REST), or view the network topology in the fablo-target/network-topology.mmd Mermaid diagram.

Installation

Fablo is distributed as a single shell script that uses a Docker image to generate the network configuration. To install it locally in your project directory:

curl fablo.io/install.sh | bash
# OR
curl fablo.io/fablo.sh > fablo && chmod +x fablo

To install it globally on your system:

sudo curl fablo.io/fablo.sh -o /usr/local/bin/fablo && sudo chmod +x /usr/local/bin/fablo

To install a given version use:

curl https://github.com/hyperledger-labs/fablo/releases/download/<version>/fablo.sh

To change version of current installation:

fablo use <version>

Note: If you install Fablo as a local script, you call it as ./fablo <command>. If you install it globally, you call fablo <command>. For the simplicity we will refer to it as fablo.

Basic usage

fablo up /path/to/fablo-config.json

The up command creates the initial configuration and starts the Hyperledger Fabric network on Docker. The network configuration is saved in $(pwd)/fablo-target. You can then manage the network with other commands such as stop, start, down, and prune.

The Fablo configuration file describes the network topology: root organization, other organizations, channels, and chaincodes. See the samples or Fablo config section for examples.

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] [gateway]

Creates a simple network configuration file (fablo-config.json) in the current directory. This is a good starting point for your Fablo journey or to set up a quick prototype.

The generated network configuration includes an orderer organization with two BFT orderer nodes and a peer organization with two peers. It uses Fabric version 3.1.0.

The fablo init command accepts several optional parameters (order doesn't matter):

• node - generates a sample Node.js chaincode
• rest - enables a simple REST API with Fablo REST as a standalone Docker container
• dev - enables chaincode hot reload mode
• gateway - generates a sample Node.js server that connects to the gateway

Sample command:

fablo init node dev

generate

fablo generate [/path/to/fablo-config.json|yaml [/path/to/fablo/target]]

Generates network configuration files in the specified 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 lose Fablo support for other commands.

If you want to use Fablo only to generate the Hyperledger Fabric network configuration, you can provide a target directory parameter or copy the generated fablo-target directory content to your 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 committing to version control.

up

fablo up [/path/to/fablo-config.json|yaml]

Starts the Hyperledger Fabric network for the given Fablo configuration file, creates channels, and installs and instantiates chaincodes. If no configuration exists, it will call the generate command for the given config file.

down, start, stop

fablo [down | start | stop]

Stops, starts, or stops the Hyperledger Fabric network for the configuration in the current directory. This is similar to the down, start, and stop commands for Docker Compose.

prune

fablo prune

Stops the network and removes the fablo-target directory.

reset and recreate

fablo reset
fablo recreate [/path/to/fablo-config.json|yaml]

• reset - combines down and up steps. Network state is lost, but the configuration is kept intact. Useful when you want a fresh network instance without any state.
• recreate - prunes the network, generates new config files, and starts the network. Useful when you've edited the fablo-config file and want to start a newer network version in one command.

validate

fablo validate [/path/to/fablo-config.json|yaml]

Validates the network configuration. This command will validate your network config and suggest necessary changes or additional tweaks. Note that this step is also executed automatically before each generate to ensure that at least critical errors are fixed.

export-network-topology

fablo export-network-topology [/path/to/fablo-config.json] [outputFile.mmd]

• outputFile.mmd: (optional) Path to the output Mermaid file. Defaults to network-topology.mmd.

Sample command:

fablo export-network-topology fablo-config.json network-topology.mmd

You can visualize the output using any Mermaid-compatible tool or online editor.

extend-config

fablo extend-config [/path/to/fablo-config.json|yaml]

Generates an extended version of the Fablo config by filling in default and computed values based on the provided configuration file and making some config parts more verbos.

snapshot and restore

Fablo supports saving state snapshots (backups) of the network and restoring them. It saves all network artifacts, certificates, and data from CA, orderer, and peer nodes. Note that the snapshot does not contain the Fablo config file and chaincode source code, as both can be located outside the Fablo working directory.

Snapshotting is useful if you want to preserve the current state of a network for future use (testing, sharing the network state, courses, etc.).

fablo snapshot <target-snapshot-path>

To restore a snapshot into the current directory, run:

fablo restore <source-snapshot-path>

Example:

1. Assume you have a working network with some state.
2. Run ./fablo snapshot /tmp/my-snapshot. This creates a file /tmp/my-snapshot.fablo.tar.gz with the network state. You don't need to stop the network before making a snapshot.
3. Run ./fablo prune to destroy the current network. If the network is present, Fablo won't be able to restore the new one from backup.
4. Run ./fablo restore /tmp/my-snapshot to restore the network.
5. Run ./fablo start to start the restored network.
6. When running external chaincodes (CCAAS), run ./fablo chaincodes install to start the CCAAS container

Typically, a snapshot of a network with little data will be less than 1 MB, making it easy to share.

fabric-docker.sh

The fabric-docker.sh script is generated alongside the Docker network configuration. It doesn't support the generate command, but other commands work the same way as in fablo. Essentially, fablo forwards some commands to this script.

If you want to use Fablo for network configuration setup only, the fabric-docker.sh file allows you to manage the network.

Managing chaincodes

chaincode(s) install

fablo chaincodes install

Installs all chaincodes. This might be useful if Fablo fails to install them automatically.

To install a single chaincode defined in the Fablo config file, run:

fablo chaincode install <chaincode-name> <version>

chaincode upgrade

fablo chaincode upgrade <chaincode-name> <version>

Upgrades the chaincode with the given name on all relevant peers. The chaincode directory is specified in the Fablo config file.

chaincode invoke

Invokes a chaincode with the specified parameters.

fablo chaincode invoke <peers-domains-comma-separated>  <channel-name>  <chaincode-name> <command> [transient] 

Sample command:

fablo chaincode invoke "peer0.org1.example.com" "my-channel1" "chaincode1" '{"Args":["KVContract:put", "name",