Deploying a Hyperledger Composer blockchain business network to Hyperledger Fabric for a single organization

In the development environment, a simple development only Hyperledger Fabric single organization, single peer network is created for you (fabric-dev-servers), along with all of the Hyperledger Composer configuration that you need in order to deploy a blockchain business network.

This tutorial will demonstrate the steps that an administrator needs to take in order to deploy a blockchain business network to an instance of Hyperledger Fabric for a single organization, including how to generate the necessary Hyperledger Composer configuration. A subsequent tutorial will demonstrate how to deploy a blockchain business network to an instance of Hyperledger Fabric for multiple organizations.

During this tutorial, you may wish to refer to the Hyperledger Fabric documentation.

Prerequisites

Before you continue, ensure that you have followed the steps in installing a development environment.

Step One: Starting a Hyperledger Fabric network

In order to follow this tutorial, you must start a Hyperledger Fabric network. You can use the simple Hyperledger Fabric network provided in the development environment, or you can use your own Hyperledger Fabric network that you have built by following the Hyperledger Fabric documentation.

The tutorial will assume that you use the simple Hyperledger Fabric network provided in the development environment. If you use your own Hyperledger Fabric network, then you must map between the configuration detailed below and your own configuration and it should be a single organization network.

Start a clean Hyperledger Fabric by running the following commands:

cd ~/fabric-dev-servers
export FABRIC_VERSION=hlfv12
./stopFabric.sh
./teardownFabric.sh
./downloadFabric.sh
./startFabric.sh

Delete any business network cards that may exist in your wallet. It is safe to ignore any errors that state that the business network cards cannot be found:
```
composer card delete -c PeerAdmin@fabric-network
composer card delete -c admin@tutorial-network
```

If these commands fail, then you have network cards from a previous version and you will have to delete the file system card store.

    rm -fr ~/.composer

Step Two: Exploring the Hyperledger Fabric network

This step will explore the Hyperledger Fabric network that you have just started, so that you can understand how it has been configured, and what components it consists of. You will use all of the information in this section to configure Hyperledger Composer in subsequent steps.

Configuration files

The simple Hyperledger Fabric network provided in the development environment has been configured using the Hyperledger Fabric configuration tools cryptogen and configtxgen.

The configuration for cryptogen is stored in the file:

~/fabric-dev-servers/fabric-scripts/hlfv12/composer/crypto-config.yaml

The configuration for configtxgen is stored in the file:

~/fabric-dev-servers/fabric-scripts/hlfv12/composer/configtx.yaml

You can find more information about these configuration tools, what they do, and how to use them by reading the Hyperledger Fabric documentation.

Organizations

The simple Hyperledger Fabric network is made up of a single organization called Org1. The organization uses the domain name org1.example.com. Additionally, the Membership Services Provider (MSP) for this organization is called Org1MSP. In this tutorial, you will deploy a blockchain business network that only the organization Org1 can interact with.

Network components

The Hyperledger Fabric network is made up of several components:

A single peer node for Org1, named peer0.org1.example.com.
- The request port is 7051.
- The event hub port is 7053.
A single Certificate Authority (CA) for Org1, named ca.org1.example.com.
- The CA port is 7054.
A single orderer node, named orderer.example.com.
- The orderer port is 7050.

The Hyperledger Fabric network components are running inside Docker containers. When running Hyperledger Composer within a Docker container, the names above (for example, peer0.org1.example.com) can be used to interact with the Hyperledger Fabric network.

This tutorial will run Hyperledger Composer commands on the Docker host machine, rather than from inside the Docker network. This means that the Hyperledger Composer commands must interact with the Hyperledger Fabric network using localhost as the host name and the exposed container ports.

Users

The organization Org1 is configured with a user named Admin@org1.example.com. This user is an administrator. Administrators for an organization have the permission to install the code for a blockchain business network onto their organization's peers, and can also have the permission to start the blockchain business network, depending on configuration. In this tutorial, you will deploy a blockchain business network by acting as the user Admin@org1.example.com.

The user Admin@org1.example.com has a set of certificates and private key files stored in the directory:

~/fabric-dev-servers/fabric-scripts/hlfv12/composer/crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp

You will use some of these files later on to interact with the Hyperledger Fabric network.

In addition to the administrator, the CA (Certificate Authority) for Org1 has been configured with a default user. This default user has an enrollment ID of admin and an enrollment secret of adminpw. However, this user does not have permission to deploy a blockchain business network.

Channel

Finally, a channel named composerchannel has been created. The peer node peer0.org1.example.com has been joined to this channel. You can only deploy Hyperledger Composer blockchain business networks into existing channels, but you can create additional channels by following the Hyperledger Fabric documentation.

Step Three: Building a connection profile

A connection profile specifies all of the information required to locate and connect to the Hyperledger Fabric network, for example the host names and ports of all of the Hyperledger Fabric network components. In this step, you will create a connection profile for Hyperledger Composer to use to connect to the Hyperledger Fabric network.

Create a connection profile file called connection.json.
Give the connection profile name, version and x-type properties by adding the following three lines to the top of connection.json:
```
{
    "name": "fabric-network",
    "x-type": "hlfv1",
    "version": "1.0.0",
```
The name property in a connection profile gives a name to the Hyperledger Fabric network, so we can reference it later on. In the connection profile you have just created, the name is fabric-network. You can use any name you like for the Hyperledger Fabric network.

Hyperledger Composer is designed to be compatible with different types blockchain networks. Currently, only Hyperledger Fabric v1.x is supported, but you must specify the type of blockchain network to use. The x-type for Hyperledger Fabric v1.2 is hlfv1.

The version number is the version of this connection profile format. Currently there is only 1 version of 1.0.0.

There is also an optional property x-commitTimeout which can also be specified with defines how long Hyperledger Composer should wait for a submitted transaction to be committed to your organization's peer before giving up waiting. The default if not specified is 300 seconds.
We must specify the host names and ports of all of the peer nodes in the Hyperledger Fabric network. There is only 1 peer and we give it a label of peer0.org1.example.com.
```
    "peers": {
        "peer0.org1.example.com": {
            "url": "grpc://localhost:7051"
        }
    },
```
Here, we have specified our single peer node peer0.org1.example.com (using the host name localhost), the request port 7051, and the event hub port 7053.

The peers array can contain multiple peer nodes. If you have multiple peer nodes, you should add them all to the peers object.
We must specify the host name and port of the certificate authority (CA) in the Hyperledger Fabric network that we want to use for enrolling existing users and registering new users.
```
    "certificateAuthorities": {
        "ca.org1.example.com": {
            "url": "http://localhost:7054",
            "caName": "ca.org1.example.com"
        }
    },
```
Here we have specified our single CA ca.org1.example.com (using the hostname localhost) and the CA port 7054, and we also label this entry as ca-org1.example.com
We must specify the host names and ports of all of the ordering nodes in the Hyperledger Fabric that we want to connect to.
```
    "orderers": {
        "orderer.example.com": {
            "url": "grpc://localhost:7050"
        }
    },
```
Here, we have specified our single orderer node orderer.example.com (using the hostname localhost) and the orderer port 7050 and we also label this as orderer.example.com.

The orderers object can contain multiple orderer nodes. If you have multiple orderer nodes, you should add them all to the orderers object.
We now must specify all the organizations in the network. In this tutorial there is only 1 organization, Org1.
```
    "organizations": {
        "Org1": {
            "mspid": "Org1MSP",
            "peers": [
                "peer0.org1.example.com"
            ],
            "certificateAuthorities": [
                "ca.org1.example.com"
            ]
        }
    },
```
Here we are describing the owners of the peers and who their certificate authority is plus we also declare the MSP id that has been defined for this organisation. In this tutorial it has been defined as Org1MSP.
We must specify the name of an existing channel. We will deploy our blockchain business network into the channel composerchannel. This is defined in the channels object.
```
    "channels": {
        "composerchannel": {
            "orderers": [
                "orderer.example.com"
            ],
            "peers": {
                "peer0.org1.example.com": {
                    "endorsingPeer": true,
                    "chaincodeQuery": true,
                    "eventSource": true
                }
            }
        }
    },
```
Here we are defined the channel composerchannel and also the orderers and peers that are part of that channel. We also specify the roles the peer will perform in this channel. In this tutorial we have added the single orderer and single peer defined earlier referenced using their labels. The peer will have the business network installed so will be a transaction endorser, able to handle chaincode queries and also generate events. The blockchain business network will be deployed to all of the specified peer nodes. Once the blockchain business network has been deployed, the specified peer nodes will be used for querying the blockchain business network, endorsing transactions, and subscribing to events.

The final section this is required is the client section. This is used by client applications (such as Hyperledger Composer) to know what organization it is representing when interacting and also some extra optional timeouts.

    "client": {
        "organization": "Org1",
        "connection": {
            "timeout": {
                "peer": {
                    "endorser": "300",
                    "eventHub": "300",
                    "eventReg": "300"
                },
                "orderer": "300"
            }
        }
    }
}

Here we are specifying that we are in Org1. The timeouts are used to determine how long to wait for a response when interacting with a peer or orderer and the values are specified in seconds. If you don't specify anything then the default is 45 seconds.

Save your changes to connection.json. The completed connection profile should look like the following:

{
    "name": "fabric-network",
    "x-type": "hlfv1",
    "version": "1.0.0",
    "peers": {
        "peer0.org1.example.com": {
            "url": "grpc://localhost:7051"
        }
    },
    "certificateAuthorities": {
        "ca.org1.example.com": {
            "url": "http://localhost:7054",
            "caName": "ca.org1.example.com"
        }
    },
    "orderers": {
        "orderer.example.com": {
            "url": "grpc://localhost:7050"
        }
    },
    "organizations": {
        "Org1": {
            "mspid": "Org1MSP",
            "peers": [
                "peer0.org1.example.com"
            ],
            "certificateAuthorities": [
                "ca.org1.example.com"
            ]
        }
    },
    "channels": {
        "composerchannel": {
            "orderers": [
                "orderer.example.com"
            ],
            "peers": {
                "peer0.org1.example.com": {
                    "endorsingPeer": true,
                    "chaincodeQuery": true,
                    "eventSource": true
                }
            }
        }
    },
    "client": {
        "organization": "Org1",
        "connection": {
            "timeout": {
                "peer": {
                    "endorser": "300",
                    "eventHub": "300",
                    "eventReg": "300"
                },
                "orderer": "300"
            }
        }
    }
}

Step Four: Locating the certificate and private key for the Hyperledger Fabric administrator

In order to deploy a blockchain business network to this Hyperledger Fabric network, we must identify ourselves as an administrator with the permissions to perform this operation. In this step, you locate the files required to identify yourself as an administrator.

The administrator for our Hyperledger Fabric network is a user called Admin@org1.example.com. The certificates and private key files for this user are stored in the directory:

~/fabric-dev-servers/fabric-scripts/hlfv12/composer/crypto-config/peerOrganizations/org1.example.com/users/Admin@org1.example.com/msp

You must first locate the certificate file for this user. The certificate is the public part of the identity. The certificate file can be found in the signcerts subdirectory and is named Admin@org1.example.com-cert.pem. If you look at the contents of this file, then you will find a PEM encoded certificate similar to the following:

Next, you must locate the private key file for this user. The private key is used to sign transactions as this identity. The private key file can be found in the keystore subdirectory. The name of the private key file is a long hexadecimal string, with a suffix of _sk, for example 114aab0e76bf0c78308f89efc4b8c9423e31568da0c340ca187a9b17aa9a4457_sk. The name will change every time the configuration is generated. If you look at the contents of this file, then you will find a PEM encoded private key similar to the following:

Remember the path to both of these files, or copy them into the same directory as the connection profile file connection.json that you created in the previous step. You will need these files in the next step.

Step Five: Creating a business network card for the Hyperledger Fabric administrator

A business network card contains all of the information required to connect to a blockchain business network and the underlying Hyperledger Fabric network. This information includes the connection profile created in step three, and the certificate and private key for the administrator located in step four.

In this step you will create a business network card for the administrator to use to deploy the blockchain business network to the Hyperledger Fabric network.

Run the composer card create command to create a business network card. You must specify the path to all three files that you either created or located in the previous steps:

composer card create -p connection.json -u PeerAdmin -c Admin@org1.example.com-cert.pem -k 114aab0e76bf0c78308f89efc4b8c9423e31568da0c340ca187a9b17aa9a4457_sk -r PeerAdmin -r ChannelAdmin

A business network card file called PeerAdmin@fabric-network.card will have been written to the current directory. Let's explore the options that we passed to the composer card create command.

-p connection.json

This is the path to the connection profile file that we created in step three.

-u PeerAdmin

This is a name that we use to refer to the administrator user. Instead of using Admin@org1.example.com everywhere, which is quite lengthy to type, we have given a name of PeerAdmin so we can easily refer to this user.

-c Admin@org1.example.com-cert.pem

This is the path to the certificate file for the user Admin@org1.example.com that we located in step four.

-k 114aab0e76bf0c78308f89efc4b8c9423e31568da0c340ca187a9b17aa9a4457_sk

This is the path to the private key file for the user Admin@org1.example.com that we located in step four.

-r PeerAdmin -r ChannelAdmin

Here, we specify which roles the user has. This information is required so that Hyperledger Composer playground knows which users are able to perform which operations. The user Admin@org1.example.com is an administrator for the Hyperledger Fabric network, and has the roles PeerAdmin (ability to install chaincode) and ChannelAdmin (ability to instantiate chaincode).

Step Six: Importing the business network card for the Hyperledger Fabric administrator

Hyperledger Composer can only use business network cards that are placed into a wallet. The wallet is a directory on the file system that contains business network cards. In this step, you will import the business network card created in step five into the wallet so that you can use the business network card in subsequent steps.

Run the composer card import command to import the business network card into the wallet:

composer card import -f PeerAdmin@fabric-network.card

Let's explore the options that we passed to the composer card import command.

-f PeerAdmin@fabric-network.card

This is the path to the business network card file that we created in step five.

You can now use this business network card by specifying the name PeerAdmin@fabric-network. You are now all set to deploy the blockchain business network to the Hyperledger Fabric network.

We are going to deploy the blockchain business network tutorial-network that is created by following the Developer Tutorial. If you haven't created a business network archive (.bna) file by following the developer tutorial, follow steps 1, 2, and 3 of the developer tutorial.

Step Seven: Installing the Hyperledger Composer business network onto the Hyperledger Fabric peer nodes

In this step, you will install your blockchain business network onto all of your organizations Hyperledger Fabric peer nodes. In Hyperledger Fabric terms, this is a chaincode install operation.

Run the composer network install command to install the Hyperledger Composer runtime onto the Hyperledger Fabric peer nodes that you specified in the connection profile file you created in step three:

composer network install -c PeerAdmin@fabric-network -a tutorial-network@0.0.1.bna

Let's explore the options that we passed to the composer network install command.

-c PeerAdmin@fabric-network

This is the name of the business network card that we imported into the wallet in step six.

-a tutorial-network@0.0.1.bna

You must install a copy of the business network. Here we specify the file name of the blockchain business network that we are deploying, tutorial-network@0.0.1.bna.

Step Eight: Starting the blockchain business network

In this step, you will start the blockchain business network. In Hyperledger Fabric terms, this is a chaincode instantiate operation.

Run the composer network start command to start the blockchain business network:

composer network start --networkName tutorial-network --networkVersion 0.0.1 -A admin -S adminpw -c PeerAdmin@fabric-network

Let's explore the options that we passed to the composer network start command.

-c PeerAdmin@fabric-network

This is the name of the business network card that we imported into the wallet in step six.

--networkName tutorial-network

This is the name of blockchain business network called tutorial-network.

--networkVersion 0.0.1

This is the version of blockchain business network called tutorial-network, defined in the version property of the package.json for the business network

-A admin

When a blockchain business network is deployed, you must create at least one participant who will be a blockchain business network administrator. This participant is responsible for onboarding other participants into the blockchain business network. Here, we are specifying that we want to create a single blockchain business network administrator called admin.

-S adminpw

This specifies that our blockchain business network administrator admin will use an enrollment secret of adminpw to request a certificate and private key from the CA (Certificate Authority). When you specify this option, the name specified for the business network administrator must be an existing enrollment ID for a user that is already registered with the CA.

Now that our blockchain business network has been started, we can interact with it using the business network card file admin@tutorial-network.card that was created.

Step Nine: Importing the business network card for the business network administrator

Run the composer card import command to import the business network card into the wallet:

composer card import -f admin@tutorial-network.card

You can now use this business network card by specifying the name admin@tutorial-network. You are now all set to interact with the running blockchain business network!

Step Ten: Testing the connection to the blockchain business network

Run the composer network ping command to test the connection to the blockchain business network:

composer network ping -c admin@tutorial-network

Check that the test result was successful, and there is a single participant listed for the business network with the name NetworkAdmin.

Conclusion

In this tutorial you have seen how to configure Hyperledger Composer with all of the information required to connect to a Hyperledger Fabric network, and how to deploy a blockchain business network to that Hyperledger Fabric network.

If you used the simple Hyperledger Fabric network provided in the development environment, why not try building your own Hyperledger Fabric network by following the Hyperledger Fabric documentation and see if you can successfully deploy a blockchain business network to it?