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

In the development environment, a simple Hyperledger Fabric 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.

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.

Start a clean Hyperledger Fabric by running the following commands:

cd ~/fabric-tools
./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 -n PeerAdmin@fabric-network
composer card delete -n admin@tutorial-network
```

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-tools/fabric-scripts/hlfv1/composer/crypto-config.yaml

The configuration for configtxgen is stored in the file:

~/fabric-tools/fabric-scripts/hlfv1/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-tools/fabric-scripts/hlfv1/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 and type properties by adding the following three lines to the top of connection.json:
```
{
  "name": "fabric-network",
  "type": "hlfv1",
```
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.0 is supported, but you must specify the type of blockchain network to use. The type for Hyperledger Fabric v1.0 is hlfv1.
The name of the MSP that is used to connect to the Hyperledger Fabric network must be specified:
```
"mspID": "Org1MSP",
```
We are connecting as Org1, and the MSP for Org1 is called Org1MSP.
We must specify the host names and ports of all of the peer nodes in the Hyperledger Fabric network that we want to connect to.
```
"peers": [
    {
        "requestURL": "grpc://localhost:7051",
        "eventURL": "grpc://localhost:7053"
    }
],
```
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 array so that Hyperledger Composer can interact with them.

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.
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.
```
"ca": {
    "url": "http://localhost:7054",
    "name": "ca.org1.example.com"
},
```
Here we have specified our single CA ca.or1.example.com (using the hostname localhost) and the CA port 7054.
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": [
    {
        "url" : "grpc://localhost:7050"
    }
],
```
Here, we have specified our single orderer node orderer.example.com (using the hostname localhost) and the orderer port 7050.

The orderers array can contain multiple orderer nodes. If you have multiple orderer nodes, you should add them all to the orderers array so that Hyperledger Composer can interact with them.
We must specify the name of an existing channel. We will deploy our blockchain business network into the channel composerchannel.
```
"channel": "composerchannel",
```
Finally, we can optionally specify a timeout for endorsing transactions when interacting with a blockchain business network.
```
  "timeout": 300
}
```
Here, we have specified a timeout of 300 seconds. If a transaction takes longer than 300 seconds to endorse, then a timeout error will be thrown.

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

{
  "name": "fabric-network",
  "type": "hlfv1",
  "mspID": "Org1MSP",
  "peers": [
      {
          "requestURL": "grpc://localhost:7051",
          "eventURL": "grpc://localhost:7053"
      }
  ],
  "ca": {
      "url": "http://localhost:7054",
      "name": "ca.org1.example.com"
  },
  "orderers": [
      {
          "url" : "grpc://localhost:7050"
      }
  ],
  "channel": "composerchannel",
  "timeout": 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-tools/fabric-scripts/hlfv1/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 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.

Step Seven: Installing the Hyperledger Composer runtime onto the Hyperledger Fabric peer nodes

Hyperledger Composer includes a component called the Hyperledger Composer runtime that provides all of the functionality to host and support a business network archive, for example data validation, error handling, transaction processor function execution, and access control. In Hyperledger Fabric terms, the Hyperledger Composer runtime is a standard chaincode.

In this step, you will install the Hyperledger Composer runtime onto all of the Hyperledger Fabric peer nodes. In Hyperledger Fabric terms, this is a chaincode install operation.

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

composer runtime install -c PeerAdmin@fabric-network -n tutorial-network

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

-c PeerAdmin@fabric-network

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

-n tutorial-network

You must install a copy of the Hyperledger Composer runtime for each blockchain business network, and specify the name of the blockchain business network. Here we specify the name of the blockchain business network that we are deploying, tutorial-network.

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 -c PeerAdmin@fabric-network -a tutorial-network.bna -A admin -S adminpw

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.

-a tutorial-network.bna

This is the path to the business network archive that contains the business network definition for our blockchain business network called tutorial-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

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?