BLCN532 Lab 1
Set up your development environment
V2.0
Introduction
This course introduces students to blockchain development for enterprise environments. Before you can develop software applications, you need to ensue your development environment is in place. That means you’ll need all the tools and infrastructure installed and configured to support enterprise blockchain software development projects.
In this lab you’ll set up your own Hyperledger Fabric development environment and install the course software from the textbook. When you finish this lab, you’ll have a working development environment and will be ready to start running and modifying blockchain applications.
The instructions in your textbook are for Mac and Linux computers. However, there is no guarantee that your installation of MacOS or Linux is completely compatible with the environment in which the commands from the textbook work properly. For that reason, I STRONGLY SUGGEST that you acquire an Ubuntu 16.04 Virtual Machine (VM) for your labs. Using an Ubuntu 16.04 VM will make the labs far easier to complete.
The instructions in this course’s labs assume that your computer runs the Windows operating system. If you run MacOS or Linux, you can get Vagrant and VirtualBox for those operating systems and follow the gist of the “Initial setup for Windows computers”.
Lab Deliverables:
To complete this lab, you must create a Lab Report file and submit the file in iLearn. The Lab Report file must be a Microsoft Word format (.docx), and have the filename with the following format:
BLCN532_SECTION_STUDENTID_LASTNAME_FIRSTNAME_Lab01.docx
· SECTION is the section number of your current course (2 digits)
· STUDENTID is your student ID number (with leading zeros)
· LASTNAME is your last name, FIRSTNAME is your first name
To get started, create a Microsoft Word document (.docx) with the correct filename for this lab. You’ll be asked to enter text and paste screenshots into the lab report file.
NOTE: All screenshots MUST be readable. Use the Ubuntu Screen Capture utility (see the lab video.) Make sure that you label each screenshot (i.e. Step 2.1.3) and provide screenshots in order. For commands that produce lots of output, I only want to see the last full screen when the command finishes. Provide FULL screenshots, NOT cropped images.
SECTION 1: Initial setup for Windows computers (Chapter 3)
Step 1.1: Install Oracle Virtualbox (Windows, Linux, MacOS)
Oracle Virtualbox is an open source virtualization environment that allows you to run multiple virtual machines and containers on a single personal computer. Virtualbox is free and it is easy to install.
In your favorite web browser, navigate to: https://www.virtualbox.org/ and click the “Download Virtualbox” button. Click the “Windows hosts” link to download the main installation executable. You should also click the “All supported platforms” under the “Extension Pack” heading to download extra software support for devices.
After you download the two files, double click each one to run the install procedure.
Step 1.2: Install Vagrant (Windows, Linux, MacOS)
Vagrant is a free virtual environment management utility. It makes the process of starting, stopping, and managing virtual machines easier. In your web browser, navigate to https://www.vagrantup.com/ then click the “Download” button, and click the version of the Windows executable you’d like to install. (Most of you should select the “64-bit” version.)
Once you download the install program, double-click the file you just downloaded to install Vagrant.
If you want more information on Vagrant and tips on getting the most out of the software, navigate to:
https://www.sitepoint.com/getting-started-vagrant-windows/ .
Step 1.3: Set up your Vagrant project
After installing all the pre-requisite pieces, you need to set up your Vagrant project. A Vagrant project defines your virtual machine environment and helps you organize your collection of VMs into a group that is easy to manage.
We’ll use the Windows PowerShell as our Windows command prompt environment. PowerShell is a very powerful command line interface that is available on all Windows computers.
To launch PowerShell, click the Windows key, type PowerShell, then click the Windows PowerShell menu entry. The figure below shows a portion of the Windows PowerShell command prompt window.
PowerShell uses your user’s home directory as its starting directory. In my case, C:Usersmicha is my home directory. For the rest of the lab, I’ll refer to this a %HOME%. Your %HOME% will be different.
1.3.1: Remove existing Vagrant projects
Follow these steps ONLY if you already have a previous Vagrant project you want to remove: (Assume the project you want to remove is located in the %HOME%vagrantHyperledger directory.)
If you DO NOT have an existing Vagrant project that you need to remove, skip to section 1.3.2.
1. PS %HOME%vagrantHyperledger> vagrant global-status
Note the id of the listed VM(s). You’ll use this id in the next command, in place of xxxxxxx.
2. PS %HOME%vagrant\Hyperledger> vagrant destroy xxxxxxx
3. PS %HOME%vagrant\Hyperledger> vagrant box remove ubuntu/xenial64
1.3.2: Create a new Vagrant project for Hyperledger
Launch PowerShell and enter the following commands: (Don’t type ‘PS %HOME%>’, that’s just the PowerShell prompt. Just type the characters in bold.)
1. PS %HOME%> mkdir vagrant
2. PS %HOME%> cd vagrant
3. PS %HOME%vagrant> mkdir Hyperledger
4. PS %HOME%vagrant> cd Hyperledger
5. PS %HOME%vagrantHyperledger> vagrant init kelly219design/ubuntu-xenial-16.04-gui-desktop-base
Make sure that you enter the line above as ONE LINE at the PowerShell prompt
6. Go to the Blackboard site (ucumberlands.blackcoard.com) and login.
7. Navigate to this course (BLCN532) -> Content for this week, Lab01.
a. Download the Vagrantfile file and copy it to the %HOME%vagrantHyperledger directory. (This will overwrite the Vagrantfile that was already there.)
8. PS %HOME%vagrantHyperledger> vagrant up
NOTE: To stop your VM type vagrant halt in PowerShell
Section 2: Install Pre-requisites (Chapter 3)
Once you have an operating Linux VM, you can start to install the Hyperledger Fabric pre-requisites. In this section you’ll install all the software and configuration pieces necessary to run the class enterprise blockchain application in Hyperledger Fabric.
Step 2.1: Install pre-reqs
2.1.1: Install dev tools
1. If you haven’t started your VM, do the following:
a. Open Windows PowerShell, then navigate to your Hyperledger project directory.
b. PS %HOME%vagrantHyperledger> vagrant up
2. Login to your VM using the username: vagrant and password: vagrant
3. Click “Search your computer” (upper left corner icon), then type terminal.
4. Click on the Terminal icon to launch a terminal with a shell prompt.
You type all the following commands in your Linux VM (at the Terminal command prompt.)
Don’t type the ‘$’ character. That is the prompt character of a regular user to remind you that this is a command you should enter in Linux. When you see a ‘#’ character, that indicates you are in an elevated privilege shell. And the ‘>’ character indicates you’re in PowerShell. Pay attention to the prompt characters – they give you valuable information about your current context.
5. $ sudo apt-get update
6. $ sudo apt-get install libltdl-dev
2.1.2: Install Docker-CE
You can find complete Docker-CE instructions/docs at: https://docs.docker.com/install/linux/docker-ce/ubuntu/
1. $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add –
2. $ sudo add-apt-repository “deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable”
Make sure that you enter the line above as ONE LINE in Linux
3. $ sudo apt-get update
4. $ sudo apt-get install docker-ce docker-ce-cli containerd.io
2.1.3: Install Docker compose
1. $ sudo curl -L “https://github.com/docker/compose/releases/download/1.23.2/docker-compose-$(uname -s)-$(uname -m)” -o /usr/local/bin/docker-compose
2. $ sudo chmod +x /usr/local/bin/docker-compose
3. $ docker-compose version
4. $ date
5. Create a screenshot of the results of steps 1 – 4 and paste it into your Lab Report File.
2.1.4: Install business network pre-reqs
1. $ curl -O https://hyperledger.github.io/composer/latest/prereqs-ubuntu.sh
2. $ chmod u+x prereqs-ubuntu.sh
3. $ ./prereqs-ubuntu.sh
4. $ date
5. Create a screenshot of the results of steps 1 – 4 and paste it into your Lab Report File.
>>> Logout (use the gear icon in the upper right corner) and log back in before continuing.
2.1.5: Install GO language
The next step is to install the GO programming language. You’ll use GO to write and modify source code files for the class blockchain application.
1. $ sudo apt-get update
2. $ wget https://dl.google.com/go/go1.12.1.linux-amd64.tar.gz
3. $ tar xvf go1.12.1.linux-amd64.tar.gz
4. $ nano ~/.profile
5. In the nano editor, add the following 2 lines after the last line in the file:
export GOPATH=$HOME/go
export PATH=$PATH:$GOPATH/bin
6. Save your file and exit nano
7. $ source .profile
8. $ go version
9. $ date
10. Create a screenshot of the results of steps 1 – 9 and paste it into your Lab Report File.
Step 2.2: Install source code and set up business network
In this step you download and install the class application source code and set up the business network.
2.2.1: Forking and Cloning the trade-finance-logistics repository
1. In a browser (in Windows) go to: https://github.com/HyperledgerHandsOn/trade-finance-logistics
2. Sign up or log in
3. Click Fork
You type all the following commands in your Linux VM (at the command prompt.)
4. $ cd $GOPATH/src
5. $ git clone https://github.com/YOUR_GIT_ID/trade-finance-logistics.git
6. $ cd $GOPATH/src
7. $ mkdir -p github.com/hyperledger
8. $ cd github.com/hyperledger
9. $ git clone https://github.com/hyperledger/fabric.git -b release-1.1
10. $ cd fabric
11. EDIT FILES *****
a. $ nano Makefile
b. Find the line starts with CHAINTOOL_RELEASE (hint: use CTRL W to search)
c. Change the line you just found to this: CHAINTOOL_RELEASE=1.1.3
d. Find the line that starts with CHAINTOOL_URL (hint: use CRTL W to search)
e. Change the line you just found to this: CHAINTOOL_URL ?= https://hyperledger.jfrog.io/hyperledger/fabric-maven/org/hyperledger/fabric-chaintool/$(CHAINTOOL_RELEASE)/fabric-chaintool-$(CHAINTOOL_RELEASE).jar
NOTE: The line above should be on a SINGLE LONG LINE (don’t break up the line into multiple lines)
f. Save the file (hint: use CRTL O to write the file)
g. Exit the nano editor (hint: use CTRL X to exit)
h. $ nano images/javaenv/Dockerfile.in
i. Find the line that starts with && curl -fsSL https://nexus.hyperledger.org
j. Change the line you just found to this: && curl -fsSL https://repo1.maven.org/maven2/org/apache/maven/apache-maven/$MAVEN_VERSION/apache-maven-$MAVEN_VERSION-bin.tar.gz
NOTE: The line above should be on a SINGLE LONG LINE (don’t break up the line into multiple lines)
k. Save the file (hint: use CRTL O to write the file)
l. Exit the nano editor (hint: use CTRL X to exit)
12. $ make docker
13. $ make configtxgen cryptogen
14. $ git clone https://github.com/hyperledger/fabric-ca.git
15. $ cd fabric-ca
16. $ make docker
17. $ date
18. Create a screenshot of the results of steps 1 – 17 and paste it into your Lab Report File.
2.2.2: Generate network cryptographic material
1. $ cd $GOPATH/src/trade-finance-logistics/network
2. $ nano ~/.profile
change last line to this (all on 1 line, not 2):
export PATH=$PATH:$GOPATH/bin:$GOPATH/src/github.com/hyperledger/fabric/build/bin:$GOPATH/src/github.com/hyperledger/fabric/build/docker/bin
3. Save file and exit nano
4. $ source ~/.profile
5. $ cryptogen generate –config=./crypto-config.yaml
6. $ date
7. Create a screenshot of the results of steps 1 – 6 and paste it into your Lab Report File.
2.2.3: Generate channel artifacts
1. $ cd $GOPATH/src/trade-finance-logistics/network
2. Execute the follow commands OR run the trade.sh script (AFTER step 9)
3. $ mkdir -p channel-artifacts
4. $ configtxgen -profile FourOrgsTradeOrdererGenesis -outputBlock ./channel-artifacts/genesis.block
5. $ configtxgen -profile FourOrgsTradeChannel -outputCreateChannelTx ./channel-artifacts/channel.tx -channelID tradechannel
6. $ configtxgen -profile FourOrgsTradeChannel -outputAnchorPeersUpdate ./channel-artifacts/ExporterOrgMSPanchors.tx -channelID tradechannel -asOrg ExporterOrgMSP
7. $ configtxgen -profile FourOrgsTradeChannel -outputAnchorPeersUpdate ./channel-artifacts/ImporterOrgMSPanchors.tx -channelID tradechannel -asOrg ImporterOrgMSP
8. $ configtxgen -profile FourOrgsTradeChannel -outputAnchorPeersUpdate ./channel-artifacts/CarrierOrgMSPanchors.tx -channelID tradechannel -asOrg CarrierOrgMSP
9. $ configtxgen -profile FourOrgsTradeChannel -outputAnchorPeersUpdate ./channel-artifacts/RegulatorOrgMSPanchors.tx -channelID tradechannel -asOrg RegulatorOrgMSP
OR (Instead of typing the commands above, the author provides a script to do it all)
1. $ ./trade.sh generate -c tradechannel
Troubleshooting help:
· If you encounter problems with your blockchain network in this lab or future labs, the ./trade.sh script may help you resolve them. If you are getting errors when trying to launch or interact with your network, try these commands at the Ubuntu command prompt:
o ./trade.sh down # If your network is up and running
o ./trade.sh clean
o ./trade.sh generate -c tradechannel
o ./trade.sh up
2.2.4: Launch the sample trade network
There are two ways to launch the sample trade network, using the docker-compose command directly, or by using the author-supplied trade.sh shell script. We’ll use the shell script in most of our activities.
1. $ cd $GOPATH/src/trade-finance-logistics/network
2. $ ./trade.sh up
3. $ date
4. Create a screenshot of the results of steps 1 – 3 and paste it into your Lab Report File.
Step 2.3: Verifying your business network
The last step in this lab is to verify that your business network is up and running.
1. Open a new terminal window in your Vagrant Hyperledger VM. Click “Search your computer” (upper left corner icon), then type terminal, then click the Terminal icon.)
2. Enter the following command:
3. $ docker ps -a
4. $ date
5. Create a screenshot of the results of steps 2 – 4 and paste it into your Lab Report File.
6. The first column in the previous output is the “container-ID”. Find the container-ID for the orderer process, and use it for the following command: (Don’t type the “<” or “>” characters)
7. $ docker logs
8. Create a screenshot of the results of step 7 and paste that screenshot into your Lab Report File.
Section 3: Wrapping up
Once you have your network up and running, the only step to complete is to learn how to properly shutdown your business network.
1. Shut down the business network in Linux:
2. $ ./trade.sh down
3. Exit from your Linux Terminal command prompt(s) (i.e. close any open Terminal windows.)
4. $ exit
5. In Windows PowerShell, shut down your Hyperledger virtual machine:
9. PS %HOME%vagrantHyperledger> vagrant halt
10. Create a snapshot (NOT A SCREENSHOT) of your Ubuntu VM in VirtualBox. This allows you to easily restore to this point if you ever need to “undo” subsequent steps and return to a known point.
a. PS %HOME%vagrantHyperledger> vagrant snapshot EndOfLab01
You should have 8 screenshots in your Lab Report File. Save your file and submit it in iLearn as a file attachment for the Lab 1 assignment.
Congratulations! You have complete lab 1.