Hyperledger Fabric-X is an open source project that builds on top of Hyperledger Fabric and tailored specifically for digital assets use-cases. Fabric-X builds on the core principles of Hyperledger Fabric (sovereign, horizontally scalable smart contract execution and a modular, agile architecture) making it well-suited to meet the governance and compliance needs of regulated digital assets.
This repository contains the hyperledger.fabricx Ansible collection, which can be used to deploy an Hyperledger Fabric-X network and distribute the components over multiple nodes.
- Installation
- Usage
- Prerequisites
- Run a sample Fabric-X network
- Supported commands
- Contributing
- License
To install the hyperledger.fabricx collection on your control node, run:
git clone https://github.com/LF-Decentralized-Trust-labs/fabric-x-ansible-collection.git ~/.ansible/collections/ansible_collections/hyperledger/fabricx
cd ~/.ansible/collections/ansible_collections/hyperledger/fabricx
ansible-galaxy collection install -r requirements.ymlNOTE: This is the recommended way if you plan to develop and change the scripts, since it allows to test directly the modified scripts avoiding to reinstall the collection at every change.
If you don't know where the COLLECTIONS_PATHS is located, or you don't plan to develop/change the Ansible scripts within the collection, you can install from source using the commands:
git clone https://github.com/LF-Decentralized-Trust-labs/fabric-x-ansible-collection.git
cd fabric-x-ansible-collection
make installThe collection provides a set of Ansible roles that can be used to deploy an Hyperledger Fabric-X network in a distributed manner. Each role is devoted to a specific component.
Each role comes with tasks and each task performs a specific operation, like starting or stopping a component. The collection comes with a set of predefined playbooks that show how to use such roles. If you adapt your inventory to work with these playbooks, you can even directly use them without having to write your own playbooks.
For example, the playbook playbooks/orderer/start.yaml shows how to use the hyperledger.fabricx.orderer role to start a Fabric-X Orderer node:
- name: Start Fabric-X Orderer components
ansible.builtin.include_role:
name: hyperledger.fabricx.orderer
tasks_from: startFor more information, please look at the Roles documentation.
To run such Ansible collection, you need to have the following prerequisites installed on your control node:
After having cloned this repository, run:
pip install -r requirements.txtThe collection comes with a playbook that can be used to automatically setup all the remote nodes at once. From your control node, run:
make install-prerequisitesIMPORTANT: the playbook install all the needed packages requiring the sudo permission. Make sure to have a passwordless sudo user in order to let the playbook succeed.
The collection contains some Ansible inventory samples and playbooks samples that could be used to start a sample Fabric-X network on your local machine.
To run it on your local machine, follow the steps hereafter indicated.
The first step consists in generating the artifacts needed by the nodes to run, which means:
- generate the crypto material through the
cryptogenCLI; - generate the genesis block through
armageddonandconfigtxgenCLIs; - build the Fabric-X component binaries for all the hosts that have been marked to use the binary instead of the containerized solution (see more the Roles documentation);
- distribute the above-mentioned artifacts on the remote nodes.
To achieve this, run:
make setupOnce the artifacts have been correctly generated and distributed, you can run them with:
make startThis command bootstraps all the components that have been indicated within the reference inventory. Once the command completes, a Fabric-X network should be running on your machine with a load of 1000 TPS (which can be incremented or decremented, see Supported Commands).
You can access Grafana dashboards (user=admin, password=admin) to see how the Fabric-X network is handling the transactions processing.
To shut the network down, run:
make teardownThe command proceeds by stopping all the running instances and also cleaning any artifact that has been generated on disk by such instances.
If you run the sample inventory on macOS, you can run in connectivity issues between containers. Indeed, on macOS Docker runs using a Linux VM, which points to a different localhost from the host (aka macOS) one.
To overcome this problem, containers need to point to host.docker.internal in order to correctly resolve the other containers. Thus, run the following command in your shell:
# add this to .bashrc or any other file sourced by your shell
export LOCAL_ANSIBLE_HOST="host.docker.internal"Moreover, since now all configuration files will point to host.docker.internal, add it as an alternative resolution name for your macOS localhost (in order to let the binaries resolve also host.docker.internal) by modifying /etc/hosts:
sudo echo "127.0.0.1 host.docker.internal" >> /etc/hostsAll the high-level commands are defined within the Makefile. To get the list of all the possible commands, run:
make helpHere there is a list of the most used commands:
| Command | Usage | Example |
|---|---|---|
| install-prerequisites | Install the needed utilities on the remote hosts. | make install-prerequisites |
| setup | Build all the artifacts and transfer them to the remote hosts. | make setup |
| start | Start the targeted hosts. | make start |
| restart | Restart the targeted hosts. | make restart |
| stop | Stop the targeted hosts. | make stop |
| clean | Clean all the generated artifacts. | make clean |
| teardown | Teardown the targeted hosts. | make teardown |
| node-exporter-start | Start a Node Exporter container on the remote hosts. | make node-exporter-start |
| node-exporter-stop | Stop the Node Exporter container on the remote hosts. | make node-exporter-stop |
| fetch-logs | Fetch the logs from the targeted hosts. | make fetch-logs |
| wipe | Wipe out the artifacts and the binaries on the remote hosts. | make wipe |
| get-metrics | Get the metrics from the targeted components. | make get-metrics |
| limit-rate | Set the TPS rate on the load generators. | make limit-rate LIMIT=1000 |
| ping | Ping the ports of the components. | make ping |
By default all the Makefile commands target all the hosts which are defined within the reference inventory. However, the playbooks have been tailored in such a way that the actions can be restricted to a sub-group (or even a single host) through the target_hosts Ansible variable, which is reflected as the TARGET_HOSTS variable in the Makefile.
For example, running:
make fabric-x-orderers startrestricts the command to the host group fabric-x-orderers defined within the inventory. The Makefile comes with a set of predefined host groups that can be used to easily restrict commands:
| Group | Target | Example |
|---|---|---|
| fabric-x | The Fabric-X network nodes (orderers+committer). | make fabric-x start |
| fabric-x-orderers | All the Fabric-X orderers. | make fabric-x-orderers start |
| fabric-x-committer | The Fabric-X committer components. | make fabric-x-committer start |
| load-generators | All the load-generators. | make load-generators start |
| monitoring | All the monitoring instances. | make monitoring start |
All these groups are reflected in the sample inventory. If you plan to use the playbooks provided with the collection, we recommend to keep the names identical in order to leverage all the playbooks capabilities.
Contributions to this project are welcomed and encouraged.
If you'd like to help improve this project, please follow these steps:
-
Fork the repository;
-
Create a new branch for your feature or bugfix:
git checkout -b your-feature-nameThis project is licensed under the Apache License 2.0.
You are free to use, modify, and distribute this software in accordance with the terms of the license.
For more details, please refer to the LICENSE file included in this repository.
