Designing a Hyperledger Fabric Network

Learn how to design a Hyperledger fabric network in this article by Petr Novotny, a research scientist at IBM Research with more than 15 years of experience in engineering and research of software systems.

Packt Publishing
Jan 26, 2019 · 11 min read

Designing a Hyperledger Fabric network

The first step in determining a Hyperledger Fabric network structure for one’s application is listing the participating organizations. Logically, an organization is a security domain and a unit of identity and credentials. It governs one or more network peers and depends on a membership service provider (MSP) to issue identities and certificates for the peers as well as clients for smart contract access privileges. The ordering service, which is the cornerstone of a Fabric network, is typically assigned its own organization. The following diagram illustrates a typical peer network structure with clients, MSPs, and logical organization groupings.

Discover and review best Blockchain softwares

The criterion for the approval of a transaction (or invocation) is an endorsement policy. It is framed in terms of the organizations that are participating in the application network and not the peers themselves:

Blockchain network with peers distributed among organizations, and clients obtaining credentials from organizations to submit queries and invocations to the chaincode

The set of peers, the organizations they belong to and the membership service providers serving each organization must be decided beforehand so that the appropriate services can be installed and run on those machines.

Our sample trade network will consist of four organizations, representing the exporter, importer, carrier, and regulator, respectively. The latter two represent the carrier and regulator entities, respectively. The exporter organization, however, represents both the exporting entity and its bank. Similarly, the importer organization represents the importing entity and its bank. Grouping entities with parties they trust into a single organization makes sense from both the perspective of security and cost. Running a Fabric peer is a heavy and costly business, so it is sufficient for a bank, which likely has more resources and a large clientele, to run such a peer on behalf of itself and its clients. A trading entity obtains the right to submit transactions or read the ledger state from its organizations in the role of a client. Our blockchain network therefore needs four peers, each belonging to a different organization. Apart from the peers, our network consists of one MSP for each of the four organizations and an ordering service running in solo mode.

The ordering service belongs to its own separate organization with an MSP. The Organizations with their MSPs, peers, and clients of our trading network are illustrated in the following diagram:

A trade network with peers, an orderer, and clients in their respective organizations

Installing prerequisites

With the design of the network in hand, let’s install the pre-requisite tools:

1. Ensure that you have the latest version of:

· Docker using

· Docker-Compose using:

2. We will be using GitHub to share the source code of our tutorial. To access GitHub, the Git client needs to be installed and configured with authentication to GitHub. For more information, visit GitHub’s official website at

3. Install the software required for the business network example from The instructions above are for Mac and Linux. Note that when using Windows, we recommend the use of a solution like Vagrant to run the development environment in a virtual machine.

4. Fabric is implemented in the Go language.

· Go is syntactically similar to C++

· We will also use Go to write chaincodes

· Go can be installed from

5. Next, we need to set up our environmental variables.

GOPATH points to a workspace for the go source code, for example:

$ export GOPATH=$HOME/go

PATH needs to include the Go bin directory used to store libraries and executables, as we can see in the following snippet:

$ export PATH=$PATH:$GOPATH/bin

Forking and cloning the trade-finance-logistics repository

Now we need to get our own copy of the original source code by forking the repository on GitHub. Then, we can clone the source code into a local machine directory with the following steps:

1. In GitHub, navigate to the repository at

2. Fork the repository: Use the Fork button at the top-right corner of the page to create a copy of the source code to your account

3. Get the clone URL: Navigate to your fork of the trade-finance-logistics repository. Click on the Clone or download button, and copy the URL

4. Clone the repository: In the Go workspace, clone the repository as follows:

$ cd $GOPATH/src$ git clone

We now have a local copy of all the trade-finance-logistics tutorial materials.

Creating and running a network configuration

The code to configure and launch our network can be found in the network folder in our repository (this is an adaptation of fabric-samples/first-network). For this exercise, we will run the entire network on a single physical or virtual machine, with the various network elements running in suitably configured Docker containers. It is assumed that the reader has a basic familiarity with containerization using Docker and configurations using Docker-compose. Once the prerequisites listed in the previous section are met, it is sufficient to run the commands in that section without any extra knowledge or configuration required of the reader.

Preparing the network

We need to perform the following steps before generating network cryptographic material:

1. Clone the Fabric ( source code repository.

2. Run make docker to build Docker images for the peers and orderers.

3. Run make configtxgen cryptogen to generate the necessary tools to run the network creation commands described in this section.

4. Clone the Fabric-CA ( source code repository.

5. Run make docker to build the Docker images for the MSPs.

Generating network cryptographic material

The first step in the configuration of a network involves the creation of certificates and signing keys for the MSP of each peer and orderer organization and for TLS-based communication. We also need to create certificates and keys for each peer and orderer node to be able to communicate with each other and with their respective MSPs. The configuration for this must be specified in a crypto-config.yaml file in the network folder in our code repository.

This file contains the organization structure, the number of peers in each organization, and the default number of users in an organization for whom certificates and keys must be created (note that an admin user is created by default). As an example, see the definition of the Importer’s organization in the file as follows:

PeerOrgs:- Name: ImporterOrgDomain: trueTemplate:Count: 1Users:Count: 2

This configuration indicates that the organization labeled ImporterOrg will contain one peer. Two non-admin users will also be created. The organization domain name to be used by the peer is also defined.

To generate cryptographic material for all the organizations, run the cryptogen command as follows:

cryptogen generate — config=./crypto-config.yaml

The output is saved to the crypto-config folder.

Generating channel artifacts

To create a network according to an organization’s structure, and to bootstrap a channel, we will need to generate the following artifacts:

· A genesis block, containing organization-specific certificates that serve to initialize the Fabric blockchain.

· Channel configuration information.

· Anchor peer configurations for each organization. An anchor peer serves as a fulcrum within an organization, for cross-organization ledger syncing using the Fabric gossip protocol.

Like the crypto-config.yaml file, channel properties are specified in a file labeled configtx.yaml, which in our source code can be found in the network folder. The high-level organization of our trade network can be found in the Profiles section as follows:

Profiles:FourOrgsTradeOrdererGenesis:Capabilities:<<: *ChannelCapabilitiesOrderer:<<: *OrdererDefaultsOrganizations:- *TradeOrdererOrgCapabilities:<<: *OrdererCapabilitiesConsortiums:TradeConsortium:Organizations:- *ExporterOrg- *ImporterOrg- *CarrierOrg- *RegulatorOrgFourOrgsTradeChannel:Consortium: TradeConsortiumApplication:<<: *ApplicationDefaultsOrganizations:- *ExporterOrg- *ImporterOrg- *CarrierOrg- *RegulatorOrgCapabilities:<<: *ApplicationCapabilities

As we can see, the channel we are going to create is named FourOrgsTradeChannel, which is defined in the profile. The four organizations participating in this channel are labeled ExporterOrg, ImporterOrg, CarrierOrg, and RegulatorOrg, each of which refers to a subsection defined in the Organizations section. The orderer belongs to its own organization called TradeOrdererOrg. Each organization section contains information about its MSP (ID as well as the location of the cryptographic material, such as keys and certificates), and the hostname and port information for its anchor peers. As an example, the ExporterOrg section contains the following:

- &ExporterOrgName: ExporterOrgMSPID: ExporterOrgMSPMSPDir: crypto-config/peerOrganizations/ Host: 7051

As you can see, the MSPDir variable (representing a folder) in this specification references the cryptographic material we generated earlier using the cryptogen tool.

To generate the channel artifacts, we use the configtxgen tool. To generate the genesis block (which will be sent to the orderer during network bootstrap), run the following command from the network folder:

configtxgen -profile FourOrgsTradeOrdererGenesis -outputBlock ./channel-artifacts/genesis.block

The FourOrgsTradeOrdererGenesis keyword corresponds to the profile name in the Profiles section. The genesis block will be saved in the genesis.block file in the channel-artifacts folder. To generate the channel configuration, run the following code:

configtxgen -profile FourOrgsTradeChannel -outputCreateChannelTx ./channel-artifacts/channel.tx -channelID tradechannel

The channel we will create is named tradechannel, and its configuration is stored in channel-artifacts/channel.tx. To generate the anchor peer configuration for the exporter organization, run:

configtxgen -profile FourOrgsTradeChannel -outputAnchorPeersUpdate ./channel-artifacts/ExporterOrgMSPanchors.tx -channelID tradechannel -asOrg ExporterOrgMSP

The same process should be repeated for the other three organizations, while changing the organization names in the preceding command.

Generating the configuration in one operation

For convenience, the script is configured to generate the channel artifacts as well as the cryptographic material using the commands and configuration files described previously. Just run the following command from within the network folder:

./ generate -c tradechannel

Although you can specify any channel name here, note that the configurations used to develop the middleware will depend on that name.

Composing a sample trade network

The last command also has the effect of generating a network configuration file, docker-compose-e2e.yaml, which is used to start the network as a set of Docker containers using the docker-compose tool. The file itself depends on the statically configured files base/peer-base.yaml and base/docker-compose-base.yaml. These files collectively specify services and their attributes and enable us to run them all in one go within Docker containers, rather than having to manually run instances of these services on one or more machines. The services we need to run are as follows:

· Four instances of a Fabric peer, one in each organization

· One instance of a Fabric orderer

· Five instances of a Fabric CA, corresponding to the MSPs of each organization

Docker images for each can be obtained from the Hyperledger project on Docker Hub (, with the images being hyperledger/fabric-peer, hyperledger/fabric-orderer, hyperledger/fabric-ca for peers, orderers, and MSPs, respectively.

The base configuration of a peer can be as follows (see base/peer-base.yaml):

peer-base:image: hyperledger/fabric-peer:$IMAGE_TAGenvironment:- CORE_VM_ENDPOINT=unix:///host/var/run/docker.sock-   CORE_VM_DOCKER_HOSTCONFIG_NETWORKMODE=${COMPOSE_PROJECT_NAME}_trade- CORE_LOGGING_LEVEL=INFO- CORE_PEER_TLS_ENABLED=true- CORE_PEER_GOSSIP_USELEADERELECTION=true- CORE_PEER_GOSSIP_ORGLEADER=false- CORE_PEER_PROFILE_ENABLED=true- CORE_PEER_TLS_CERT_FILE=/etc/hyperledger/fabric/tls/server.crt- CORE_PEER_TLS_KEY_FILE=/etc/hyperledger/fabric/tls/server.key- CORE_PEER_TLS_ROOTCERT_FILE=/etc/hyperledger/fabric/tls/ca.crtworking_dir: /opt/gopath/src/ peer node start

Fabric configuration parameters can be set here, but if you use the pre-built Docker image for fabric-peer, the defaults are sufficient to get a peer service up and running. The command to run the peer service is specified in the last line of the configuration as peer node start; if you wish to run a peer by downloading the Fabric source and building it on your local machine, this is the command you will have to run. Also make sure you configure the logging level appropriately using the CORE_LOGGING_LEVEL variable. In our configuration, the variable is set to INFO, which means that only informational, warning, and error messages will be logged. If you wish to debug a peer and need more extensive logging, you can set this variable to DEBUG.

Furthermore, we need to configure the hostnames and ports for each peer and sync the cryptographic material generated (using cryptogen) to the container filesystem. The peer in the exporter organization is configured in base/docker-compose-base.yaml as follows: peer-base.yamlservice: peer-baseenvironment:- CORE_PEER_LOCALMSPID=ExporterOrgMSPvolumes:- /var/run/:/host/var/run/- ../crypto-config/peerOrganizations/ ../crypto-config/peerOrganizations/ 7051:7051- 7053:7053

As indicated by the extends parameter, this extends the base configuration. Note that the ID (CORE_PEER_ID) matches that which is specified for this peer in configtx.yaml. This identity is the hostname for the peer running in the exporter organization and will be used in the middleware code. The volumes section indicates the rules for copying the cryptographic material generated in the crypto-config folder to the container. The peer service itself listens on port 7051 and the port that clients can use to subscribe to events is set to 7053.

The configuration of the orderer service is similar, as the following snippet from base/docker-compose-base.yaml indicates: hyperledger/fabric-orderer:$IMAGE_TAGenvironment:- ORDERER_GENERAL_LOGLEVEL=INFO……command: orderer……

The command to start the orderer is simply orderer, as the code indicates. The logging level can be configured using the ORDERER_GENERAL_LOGLEVEL variable and is set to INFO in our configuration.

The actual network configuration that we will run is based on a file named docker-compose-e2e.yaml. This file does not exist in the repository but is rather created by the command ./ generate -c tradechannel, which we ran earlier to generate channel and cryptographic material. This file depends on base/docker-compose-base.yaml (and indirectly base/peer-base.yaml) as you can see by examining the file contents. It is actually created from a template YAML file named docker-compose-e2e-template.yaml, which you can find in the network folder. The template file contains variables as stand-ins for key filenames that are generated using cryptogen. When docker-compose-e2e.yaml is generated, those variable names are replaced with actual filenames within the crypto-config folder.

For example, consider the exporter-ca section in docker-compose-e2e-template.yaml:

exporter-ca:image: hyperledger/fabric-ca:$IMAGE_TAGenvironment:……- FABRIC_CA_SERVER_TLS_KEYFILE=/etc/hyperledger/fabric-ca-server-config/EXPORTER_CA_PRIVATE_KEY……command: sh -c ‘fabric-ca-server start — ca.certfile /etc/hyperledger/fabric-ca-server-config/ — ca.keyfile /etc/hyperledger/fabric-ca-server-config/EXPORTER_CA_PRIVATE_KEY -b admin:adminpw -d’

Now, look at the same section in the generated file docker-compose-e2e.yaml:

exporter-ca:image: hyperledger/fabric-ca:$IMAGE_TAGenvironment:……- FABRIC_CA_SERVER_TLS_KEYFILE=/etc/hyperledger/fabric-ca-server-config/ cc58284b6af2c33812cfaef9e40b8c911dbbefb83ca2e7564e8fbf5e7039c22e_sk……command: sh -c ‘fabric-ca-server start — ca.certfile /etc/hyperledger/fabric-ca-server-config/ — ca.keyfile /etc/hyperledger/fabric-ca-server-config/cc58284b6af2c33812cfaef9e40b8c911dbbefb83ca2e7564e8fbf5e7039c22e_sk -b admin:adminpw -d’

As you can see, the variable EXPORTER_CA_PRIVATE_KEY has been replaced with cc58284b6af2c33812cfaef9e40b8c911dbbefb83ca2e7564e8fbf5e7039c22e_sk, both in the environment variable and in the command. If you now examine the contents of the crypto-config folder, you will notice that there exists a file named cc58284b6af2c33812cfaef9e40b8c911dbbefb83ca2e7564e8fbf5e7039c22e_sk in the folder crypto-config/peerOrganizations/ This file contains the exporter organization’s MSP’s private (secret) signing key.

Let us now look at the configuration of an MSP in more detail, taking the example of the exporter organization MSP, as specified in docker-compose-e2e.yaml:

exporter-ca:image: hyperledger/fabric-ca:$IMAGE_TAGenvironment:- FABRIC_CA_HOME=/etc/hyperledger/fabric-ca-server- FABRIC_CA_SERVER_CA_NAME=ca-exporterorg- FABRIC_CA_SERVER_TLS_ENABLED=true- FABRIC_CA_SERVER_TLS_CERTFILE=/etc/hyperledger/fabric-ca-server-config/ FABRIC_CA_SERVER_TLS_KEYFILE=/etc/hyperledger/fabric-ca-server-config/cc58284b6af2c33812cfaef9e40b8c911dbbefb83ca2e7564e8fbf5e7039c22e_skports:- “7054:7054”command: sh -c ‘fabric-ca-server start — ca.certfile /etc/hyperledger/fabric-ca-server-config/ — ca.keyfile /etc/hyperledger/fabric-ca-server-config/cc58284b6af2c33812cfaef9e40b8c911dbbefb83ca2e7564e8fbf5e7039c22e_sk -b admin:adminpw -d’volumes:- ./crypto-config/peerOrganizations/ ca_peerExporterOrgnetworks:- trade

The service that will run in the MSP is the fabric-ca-server, listening on port 7054, bootstrapped with the certificates and keys created using cryptogen, and using the default login and password (admin and adminpw, respectively) configured in the fabric-ca image. The command to start an instance of a Fabric CA server is fabric-ca-server start …, as you can see in the preceding code.

Peers as well as CAs are configured for TLS-based communication, as indicated in the preceding configurations. The reader must note that if TLS is disabled in one, it must be disabled in the other too.

Also, as can be observed by examining docker-compose-e2e.yaml, we do not create a Fabric CA server (and container) for the orderer’s organization. For this exercise, statically created admin users and credentials for the orderer are sufficient; we will not be registering new orderer organization users dynamically, so a Fabric CA server is not needed.

If you found this article interesting, you can explore Hands-On Blockchain with Hyperledger to leverage the power of Hyperledger Fabric to develop Blockchain-based distributed ledgers with ease. Hands-On Blockchain with Hyperledger is an easy reference to explore and build blockchain networks using Hyperledger technologies.


Coinmonks is a non-profit Crypto educational publication.

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store