Alexander Al Basosi, Arjun Nedungadi | Published March 24, 2018
Archived date: 2019-05-01
Note: IBM Blockchain Platform now utilizes Hyperledger Fabric for end-to-end development. Users may use Hyperledger Composer at their choice, but IBM will not provide support for it.
After completing this how-to guide, you will be able to:
A Unix-based operating system. The Hyperledger Fabric environment can only be set up on Unix environments, so for windows users, you have to install a virtual machine and set up the environment as such. For the purposes of this demo, we’re going to be setting up a Ubuntu OS on VirtualBox.
A Hyperledger Fabric environment installed on your computer.
For Ubuntu Users
The following are prerequisites for installing the required development tools:
Operating Systems: Ubuntu Linux 14.04 / 16.04 LTS (both 64-bit), or Mac OS 10.12
Docker Engine: Version 17.03 or higher
Docker-Compose: Version 1.8 or higher
Node: 8.9 or higher (note version 9 is not supported)
git: 2.9.x or higher
A code editor of your choice, we recommend VSCode.
If installing Hyperledger Composer using Linux, be aware of the following advice:
Login as a normal user, rather than root.
Do not su to root.
When installing prerequisites, use curl, then unzip using sudo.
Run prereqs-ubuntu.sh as a normal user. It may prompt for root password as some of it's actions are required to be run as root.
Do not use npm with sudo or su to root to use it.
Avoid installing node globally as root.**
If you’re running on Ubuntu, you can download the prerequisites using the following commands:
curl -O https://hyperledger.github.io/composer/prereqs-ubuntu.sh
chmod u+x prereqs-ubuntu.sh
curl -O https://hyperledger.github.io/composer/prereqs-ubuntu.sh
chmod u+x prereqs-ubuntu.sh
For Mac Users
To go through this guide, it will take an estimated 45 minutes to have an end-to-end Blockchain application up and running on Hyperledger Fabric.
Follow these instructions to obtain the Hyperledger Composer development tools (primarily used to create Business Networks) and stand up a Hyperledger Fabric (primarily used to run/deploy your Business Networks locally). Note that the Business Networks you create can also be deployed to Hyperledger Fabric runtimes in other environments e.g. on a cloud platform: https://hyperledger.github.io/composer/v0.19/installing/development-tools.html
Set up the Business Network
Head over to the Composer Playground: https://composer-playground.mybluemix.net/
Select “Deploy a Business Network”
Under the “Model Network Starter Template”, select “browse”, and choose the firstname.lastname@example.org file from this repository.
You should be presented with the following screen:
We will create multiple instances of type Entity (i.e. Factory).
Here we define the transactions that will take place on the Blockchain, such as changing the state of the pizza and which entity owns the pizza.
The ChangeStateToProduction function will change the state of the current pizza to Production.
The same applies with the other three states.
The ChangeOwner function will change the owner of the pizza to a new owner.
You should see a new Pizza asset being created.
You should see a notification pop up saying “Submit Transaction Successful”. You can double-check by selecting “All Transactions” in the left pane, under Transactions.
That’s it! You’re ready to deploy your business network to the Hyperledger Fabric.
Create the .bna file
Once you have the environment set up, it’s time to package everything into a .bna file. In order to do this, we’re going to use a Yeoman generator to create a skeleton business network, then replace the model, script, and access control files with the ones we created earlier on in the tutorial.
Enter pizza-on-the-blockchain for the network name, and desired information for description, author name, and author email.
Select Apache-2.0 as the license.
Select org.acme.biznet as the namespace.
cd into the folder which was just created and replace the contents of /pizza-on-the-blockchain/lib/org.example.biznet.cto with the model file generated earlier on in the tutorial.
Replace the contents of /pizza-on-the-blockchain/lib/logic.js with the script file generated earlier on in the tutorial.
Create a new file in the pizza-on-the-blockchain folder, called permissions.acl and paste the contents of the Access Control file generated earlier on in the tutorial.
Now that you have your busines network, it’s time to package it up into a .bna file. In the pizza-on-the-blockchain directory, enter the following command:
composer archive create -t dir -n .
After the command has run, a business network archive file called email@example.com has been created in the tutorial-network directory.
After creating the .bna file, the business network can be deployed to the instance of Hyperledger Fabric. Normally, information from the Fabric administrator is required to create a PeerAdmin identity, with privileges to deploy chaincode to the peer. However, as part of the development environment installation, a PeerAdmin identity has been created already.
After the runtime has been installed, a business network can be deployed to the peer. For best practice, a new identity should be created to administrate the business network after deployment. This identity is referred to as a network admin.
A PeerAdmin business network card with the correct credentials is already created as part of development environment installation.
Deploying a business network to the Hyperledger Fabric requires the Hyperledger Composer chaincode to be installed on the peer, then the business network archive (.bna) must be sent to the peer, and a new participant, identity, and associated card must be created to be the network administrator. Finally, the network administrator business network card must be imported for use, and the network can then be pinged to check it is responding.
composer runtime install --card PeerAdmin@hlfv1 --businessNetworkName pizza-on-the-blockchain
The composer runtime install command requires a PeerAdmin business network card (in this case one has been created and imported in advance), and the name of the business network.
composer runtime install
composer network start --card PeerAdmin@hlfv1 --networkAdmin admin --networkAdminEnrollSecret adminpw --archiveFile firstname.lastname@example.org --file networkadmin.card
The composer network start command requires a business network card, as well as the name of the admin identity for the business network, the file path of the .bna and the name of the file to be created ready to import as a business network card.
composer network start
composer card import --file networkadmin.card
The composer card import command requires the filename specified in composer network start to create a card.
composer card import
composer network ping --card admin@pizza-on-the-blockchain
The composer network ping command requires a business network card to identify the network to ping.
composer network ping
Hyperledger Composer can generate a bespoke REST API based on a business network. For developing a web application, the REST API provides a useful layer of language-neutral abstraction.
Enter admin@pizza-on-the-blockchain as the card name.
Select never use namespaces when asked whether to use namespaces in the generated API.
Select No when asked whether to secure the generated API.
Select Yes when asked whether to enable event publication.
Select No when asked whether to enable TLS security.
The generated API is connected to the deployed blockchain and business network.
Once the REST server is up and running, head over to https://localhost:3000/explorer
It should look a little like this:
This is a Python Flask web application built as an interface for the Blockchain network running on Hyperledger Fabric. The application utilises REST APIs (generated using the Composer REST Server) to connect to the Blockchain network and perform GET, POST and PUT requests.
This application was built with the Flask Microframework. The UI of the application was built with MaterializeCSS, a front-end framework based on Material Design.
How to run
pip install -r requirements.txt
Please feel free to contact me with any questions/comments.
Once you start up the application, you should be able to see this page:
Browse to the Factory page, and select Production as the Pizza state. Press Submit.
You can see the Current Status has changed to production. Now, when filling the form, select Freezing. Press Submit.
Now, try Packaging.
Finally, select Distribution.
Now, select Transfer Ownership, to transfer the ownership of the pizza to the Wholesaler. This will automatically take you to the Wholesaler page, and you can see the transaction issued onto the Blockchain.
Select Transfer Ownership again.
Select Transfer Ownership one more time.
From here, the Customer can keep track of their pizza through the entire process.
We showed you how to create a simple business network using Hyperledger Composer Playground, export it and create a business network archive file, and deploy it to the Hyperledger Fabric. We also showed how you can spin up a REST server for your applications to consume, and demonstrated that fact by connecting a Python-based application to the Blockchain to realize the use-case of a frozen pizza supply chain.
May 6, 2019
Back to top