How to Build a Hyperledger Fabric Network

A Practical, Step-by-Step Guide for Developers

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.

Start Building Get Development Support

All Guides

How to Build a Hyperledger Fabric Network

How to Launch a Memecoin: From Idea to Token and Community What Is Account Abstraction (ERC-4337)?

In This Guide

Prerequisites

Before you begin, ensure you have the following installed and configured.

🔧

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

A well-designed network is crucial. Define your consortium's structure before writing any configuration.

🏢

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)

Every entity in a Fabric network needs a cryptographic identity (certificates and private keys).

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.

text

**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

Use the `configtxgen` tool to create the genesis block for the ordering service and channel configuration transactions.

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)

Define and run the network components as Docker containers using a `docker-compose.yaml` file.

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.

text

**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

With the network running, you can create a private communication channel for your organizations.

1️⃣

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️⃣

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️⃣

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️⃣

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)

Deploy the smart contract that defines your application's business logic.

1️⃣

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️⃣

2. Install on Peers

Each organization must install the chaincode package on their endorsing peers using `peer lifecycle chaincode install`.

3️⃣

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️⃣

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

Invoke and query your deployed chaincode to read and write to the ledger.

rust

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

A common requirement is to expand the consortium by adding a new member.

🔑

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

Key considerations for securing your new Fabric network.

🛡️

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.