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
, namedpeer0.org1.example.com
.- The request port is 7051.
- The event hub port is 7053.
- A single Certificate Authority (CA) for
Org1
, namedca.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
andtype
properties by adding the following three lines to the top ofconnection.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 isfabric-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 forOrg1
is calledOrg1MSP
.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 namelocalhost
), 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 thepeers
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 hostnamelocalhost
) 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 hostnamelocalhost
) 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 theorderers
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:
-----BEGIN CERTIFICATE-----
MIICGjCCAcCgAwIBAgIRANuOnVN+yd/BGyoX7ioEklQwCgYIKoZIzj0EAwIwczEL
MAkGA1UEBhMCVVMxEzARBgNVBAgTCkNhbGlmb3JuaWExFjAUBgNVBAcTDVNhbiBG
cmFuY2lzY28xGTAXBgNVBAoTEG9yZzEuZXhhbXBsZS5jb20xHDAaBgNVBAMTE2Nh
Lm9yZzEuZXhhbXBsZS5jb20wHhcNMTcwNjI2MTI0OTI2WhcNMjcwNjI0MTI0OTI2
WjBbMQswCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEWMBQGA1UEBxMN
U2FuIEZyYW5jaXNjbzEfMB0GA1UEAwwWQWRtaW5Ab3JnMS5leGFtcGxlLmNvbTBZ
MBMGByqGSM49AgEGCCqGSM49AwEHA0IABGu8KxBQ1GkxSTMVoLv7NXiYKWj5t6Dh
WRTJBHnLkWV7lRUfYaKAKFadSii5M7Z7ZpwD8NS7IsMdPR6Z4EyGgwKjTTBLMA4G
A1UdDwEB/wQEAwIHgDAMBgNVHRMBAf8EAjAAMCsGA1UdIwQkMCKAIBmrZau7BIB9
rRLkwKmqpmSecIaOOr0CF6Mi2J5H4aauMAoGCCqGSM49BAMCA0gAMEUCIQC4sKQ6
CEgqbTYe48az95W9/hnZ+7DI5eSnWUwV9vCd/gIgS5K6omNJydoFoEpaEIwM97uS
XVMHPa0iyC497vdNURA=
-----END CERTIFICATE-----
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:
-----BEGIN PRIVATE KEY-----
MIGHAgEAMBMGByqGSM49AgEGCCqGSM49AwEHBG0wawIBAQQg00IwLLBKoi/9ikb6
ZOAV0S1XeNGWllvlFDeczRKQn2uhRANCAARrvCsQUNRpMUkzFaC7+zV4mClo+beg
4VkUyQR5y5Fle5UVH2GigChWnUoouTO2e2acA/DUuyLDHT0emeBMhoMC
-----END PRIVATE KEY-----
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?