How to Build a Hyperledger Fabric Network
Move beyond the test network. This guide walks you through the entire process of designing, configuring, and launching a multi-organization Hyperledger Fabric network, empowering you to build robust enterprise blockchain solutions.
Prerequisites
Core Tools
Install Git for version control and cURL for downloading binaries. A modern terminal/shell is also required.
Docker and Docker Compose
Fabric components run in Docker containers. Install the latest versions of Docker and Docker Compose. Ensure the Docker daemon is running.
Go Programming Language
Required for running many Fabric tools and for developing chaincode in Go. Install a recent version (e.g., 1.18+).
Fabric Binaries and Samples
Download the `fabric-samples` repository from GitHub and run the `bootstrap.sh` script to pull the required Fabric Docker images and platform-specific binaries (`cryptogen`, `configtxgen`, `peer`, etc.).
Step 0: Planning Your Network
Define Organizations
Identify all participating organizations. Each organization will have its own peers, users, and Membership Service Provider (MSP) to define its identity.
Plan Peers and Orderers
Decide how many peers each organization will have. Plan the ordering service topology (e.g., a Raft cluster with 3 or 5 orderers for fault tolerance).
Design Channels
Determine the channels needed for private communication. Which organizations will be members of each channel? A channel is a private ledger between specific members.
Choose Identity Management
Decide between `cryptogen` for quick testing or a full Fabric CA setup for more robust, production-like identity management. This guide will cover both.
Step 1: Generating Crypto Material (Identities)
cryptogen is a utility that quickly generates crypto material based on a crypto-config.yaml file. It's ideal for development and testing but not recommended for production. It creates a folder structure containing the MSPs for each defined peer, orderer, and user.
Example crypto-config.yaml:
OrdererOrgs: - Name: Orderer Domain: example.com Specs: - Hostname: orderer PeerOrgs: - Name: Org1 Domain: org1.example.com EnableNodeOUs: true Template: Count: 1 Users: Count: 1
Command: cryptogen generate --config=./crypto-config.yaml --output="organizations"
Step 2: Generating Configuration Artifacts
This file is the blueprint for your network's structure. It defines organizations, their MSPs, consortiums, and profiles for generating different artifacts. Key sections include:
- Organizations: Defines each org, its name, MSPDir, and anchor peers.
- Orderer: Defines the ordering service type (e.g., Raft), addresses, and policies.
- Channel: Defines default channel policies.
- Profiles: Combines the above sections to create templates for specific artifacts (e.g., a profile for the genesis block, another for a channel transaction).
Step 3: Bringing Up the Network (Docker Compose)
Your Docker Compose file will define the orderer nodes. For a Raft setup, you'll define multiple orderer services. Key environment variables include the location of the genesis block, MSP paths, and TLS certificates.
Example Snippet:
services: orderer.example.com: container_name: orderer.example.com image: hyperledger/fabric-orderer environment: - FABRIC_LOGGING_SPEC=INFO - ORDERER_GENERAL_LISTENADDRESS=0.0.0.0 - ORDERER_GENERAL_GENESISMETHOD=file - ORDERER_GENERAL_GENESISFILE=/var/hyperledger/orderer/orderer.genesis.block - ORDERER_GENERAL_LOCALMSPID=OrdererMSP volumes: - ./system-genesis-block/genesis.block:/var/hyperledger/orderer/orderer.genesis.block - ../organizations/ordererOrganizations/example.com/orderers/orderer.example.com/msp:/var/hyperledger/orderer/msp
Step 4: Creating and Joining a Channel
1. Create the Channel
Using the CLI container, execute the `peer channel create` command. This sends the channel configuration transaction (e.g., `mychannel.tx`) to the ordering service, which creates the channel genesis block.
2. Join Peers to the Channel
Each peer that needs to be part of the channel must execute the `peer channel join` command. This command fetches the channel genesis block from the orderer and makes the peer part of the channel.
3. Set Anchor Peers
For gossip communication to work across organizations, at least one peer per organization must be designated as an anchor peer. This is done by submitting the anchor peer update transaction created earlier.
4. Verify Channel Setup
Verify that all peers have successfully joined the channel by checking their logs or by using the `peer channel getinfo` command from the CLI.
Step 5: Deploying Chaincode (Fabric 2.x Lifecycle)
1. Package the Chaincode
Use the `peer lifecycle chaincode package` command to create a chaincode package (`.tar.gz`). This bundles your source code and metadata.
2. Install on Peers
Each organization must install the chaincode package on their endorsing peers using `peer lifecycle chaincode install`.
3. Approve for Organization
Each organization on the channel must approve a chaincode definition, specifying the name, version, and endorsement policy, using `peer lifecycle chaincode approveformyorg`.
4. Commit to Channel
Once enough organizations have approved (based on the channel's lifecycle policy), one organization can commit the chaincode definition to the channel using `peer lifecycle chaincode commit`. The chaincode is now active.
Step 6: Interacting with the Network
The peer CLI is a powerful tool for testing and administration. You can use it to directly invoke and query chaincode functions.
Invoke Command:
peer chaincode invoke -o orderer.example.com:7050 --channelID mychannel --name mycc -c '{"function":"CreateAsset","Args":["asset1","blue","5","Tom","1300"]}'
Query Command:
peer chaincode query -C mychannel -n mycc -c '{"Args":["ReadAsset","asset1"]}'
Scaling: Adding a New Organization to a Channel
Generate Crypto Material
Generate the MSP and other crypto material for the new organization using `cryptogen` or Fabric CA.
Update Channel Config
Fetch the latest channel configuration block, add the new organization's definition to it, and compute a configuration update transaction using the `configtxlator` tool.
Sign and Submit Update
The configuration update must be signed by the required existing channel members (according to the modification policy). Once signed, the update is submitted to the channel.
Join and Install
The new organization's peers can now join the channel. They will also need to install any chaincode they are expected to endorse.
Security Best Practices for Network Setup
Use Fabric CA for Production
Never use `cryptogen` for a production network. Fabric CA provides robust identity management, including certificate revocation, which is critical for security.
Enable TLS Everywhere
Ensure Transport Layer Security (TLS) is enabled for all communication between network components (peers, orderers, clients) to encrypt data in transit.
Secure Private Keys
Protect all private keys generated for users, peers, and orderers. Use Hardware Security Modules (HSMs) for production environments to securely store private keys.
Least Privilege Principle
Configure policies (endorsement, lifecycle, channel) and access control within chaincode based on the principle of least privilege. Grant entities only the permissions they absolutely need.
Troubleshooting Common Issues
Frequently Asked Questions
Additional Resources
Ready to Start Building?
Let's bring your Web3 vision to life.
From concept to deployment, ChainScore helps you architect, build, and scale secure blockchain solutions.