Follow these steps to create a local VM capable of serving a Composer Business Network as a REST API endpoint. To begin, you will need an installation of Vagrant with VirtualBox. After getting the vm configured, continue by following the hyperledger developer setup steps for a local envionment from https://hyperledger.github.io/composer/latest/installing/development-tools.html . Finally, after you have the local Composer REST server running locally, you'll configure a Secure Gateway instance to expose the API on the IBM Cloud.
-
Create a directory for the project:
mkdir composer
-
Copy the contents of the Vagrantfile in this gist into the directory by copying to the clipboard, pasting into the terminal and then pressing control-D to complete creating the file.
cd composer cat > Vagrantfile ctrl-D
-
Start up the Vagrant image (this may take a little while)
vagrant up
-
Once the vm is up, log in to get started configuring hyperledger fabric
vagrant ssh
-
Follow the pre-requisite setup steps for a local hyperledger composer environment for Ubuntu from https://hyperledger.github.io/composer/latest/installing/installing-prereqs.html . Do this as an ordinary user and not a root user on the vm. Log out from vagrant with
exit
and reconnect withvagrant ssh
when prompted.curl -O https://hyperledger.github.io/composer/latest/prereqs-ubuntu.sh chmod u+x prereqs-ubuntu.sh ./prereqs-ubuntu.sh
-
After installing pre-requisites, continue with setting up the hyperledger fabric local development environment from https://hyperledger.github.io/composer/latest/installing/development-tools.html starting with the CLI tools.
npm install -g [email protected] npm install -g [email protected] npm install -g [email protected] npm install -g yo
-
Install composer playground.
npm install -g [email protected]
-
Optional: follow steps to set up IDE (Step Three from https://hyperledger.github.io/composer/latest/installing/development-tools.html )
-
Complete Step 4 from the setup to get hyperledger fabric docker images installed.
mkdir ~/fabric-dev-servers && cd ~/fabric-dev-servers curl -O https://raw.githubusercontent.com/hyperledger/composer-tools/master/packages/fabric-dev-servers/fabric-dev-servers.tar.gz tar -xvf fabric-dev-servers.tar.gz cd ~/fabric-dev-servers export FABRIC_VERSION=hlfv12 ./downloadFabric.sh
-
Continue with steps in controlling the dev environment including the first time setup of the PeerAdmin card and starting the network.
cd ~/fabric-dev-servers export FABRIC_VERSION=hlfv12 ./startFabric.sh ./createPeerAdminCard.sh
-
Start up composer-playground. Note, this will not start up a browser session automatically as it says in the documenation because the command is running inside the vm instead of on your workstation. Once started point a browser at http://localhost:8080/ (which should be mapped by the Vagrantfile configuration to the vm).
composer-playground
-
Develop a business network and test in the composer playground as usual. If you've never used composer playground, the tutorial https://hyperledger.github.io/composer/latest/tutorials/playground-tutorial is a good place to start.
-
Once you have completed testing the intended business network, deploy the composer REST server, providing the card for the network owner. See Step Five from https://hyperledger.github.io/composer/latest/tutorials/developer-tutorial for other responses to the input. The Secure Gateway connectivity steps here were tested with these options.
composer-rest-server ? Enter the name of the business network card to use: admin@marbles-network ? Specify if you want namespaces in the generated REST API: always use namespaces ? Specify if you want to use an API key to secure the REST API: No ? Specify if you want to enable authentication for the REST API using Passport: No ? Specify if you want to enable the explorer test interface: Yes ? Specify a key if you want to enable dynamic logging: ? Specify if you want to enable event publication over WebSockets: Yes ? Specify if you want to enable TLS security for the REST API: No To restart the REST server using the same options, issue the following command: composer-rest-server -c admin@marbles-network -n always -u true -w true Discovering types from business network definition ... Discovering the Returning Transactions.. Discovered types from business network definition Generating schemas for all types in business network definition ... Generated schemas for all types in business network definition Adding schemas for all types to Loopback ... Added schemas for all types to Loopback Web server listening at: http://localhost:3000 Browse your REST API at http://localhost:3000/explorer
-
Test the REST API server out by opening http://localhost:3000/explorer in a browser.
-
Open the IBM Cloud catalog entry for Secure Gateway https://console.bluemix.net/catalog/services/secure-gateway and create a Secure Gateway instance in your IBM Cloud account. You will need either a paid account or Trial promo code. The Essentials service plan is sufficient for implementing traffic forwarding for a development hyperledger fabric network with a capacity of 500 MB/month of data transfer.
-
Create a Gateway in the Secure Gateway Service Details panel. You may choose any name, but Blockchain may be an appropriate name to use. Keep the other gateway default settings of Requre security token to connect clients and Token expriation of 90 days. Click on the Add Gateway button to create the gateway.
-
Click on the Connect Client button on the Secure Gateway Service Details panel to begin setting up the client that will run on the vm and connect to the Secure Gateway service.
-
Choose Docker as the option to connect the client and copy the provided
docker run
command with the Gateway id and security token. -
Open a new local terminal window, change directory to the folder with the
Vagrantfile
and then connect to the vm usingvagrant ssh
. Paste thedocker run
command into the terminal which will start the Secure Gateway client and leave a CLI running in the terminal. Do not close this terminal. After the container starts, you will see messages like the following indicating a successful connection.[2018-10-20 18:34:01.451] [INFO] (Client ID 1) No password provided. The UI will not require a password for access [2018-10-20 18:34:01.462] [WARN] (Client ID 1) UI Server started. The UI is not currently password protected [2018-10-20 18:34:01.463] [INFO] (Client ID 1) Visit localhost:9003/dashboard to view the UI. [2018-10-20 18:34:01.760] [INFO] (Client ID 11) Setting log level to INFO [2018-10-20 18:34:02.153] [INFO] (Client ID 11) The Secure Gateway tunnel is connected [2018-10-20 18:34:02.304] [INFO] (Client ID HxzoYUW6z74_PZ9) Your Client ID is HxzoYUW6z74_PZ9 HxzoYUW6z74_PZ9>
-
On another terminal on the vagrant vm, use the
ip address show
command to find the IP address of the vm. Many interfaces will be listed, select the one that begins withenp
oreth
. In the examples that follow, the vm IP address is10.0.2.15
. -
Return to the terminal for the Secure Gateway client docker container, create an acl entry that will allow traffic to the composer REST API server running on port 3000.
acl allow 10.0.2.15:3000 1
-
In this series of steps, you will define a basic http connection through the Secure Gateway service to your running copy of the composer REST API server. For more advanced security settings refer to the Secure Gateway documentation. To get started, on the Secure Gateway Service Details panel, click on the tile for the Gateway you named and created in step 16. This will open the destinations tab. Click on the "+" button to open the Destination creation wizard. Select the Guided Setup option.
-
For the "Where is your resource located?" item, select On-premises and then click on Next.
-
For "What is the host and port of your destination?", put in the IP address from step 20 as the hostname and 3000 as the port. Then click on Next.
-
For the connection protocol, select HTTP and then click on Next.
-
For the destination authentication, select None and then click on Next.
-
Skip entry of the IP address and ports for the options to "... make your destination private, add IP table rules below" step and click on Next.
-
Enter a name like
Composer REST server
for the name of the destination and click on Add Destination -
Click on the gear icon for the tile of the destination that was just created to display the details. Copy the Cloud Host : Port - this will look something like:
cap-sg-prd-2.integration.ibmcloud.com:17870
. This is the Cloud endpoint that can be accessed and traffic will be forwarded by the Secure Gateway service to the running Composer REST server. -
Append /explorer after the host and port and open this url in a web browser. For the example, the final url would be:
http://cap-sg-prd-2.integration.ibmcloud.com:17870/explorer/
.
At this point you should be able to access the Composer REST server to perform actions in the deployed business network, using the hostname and port from the Secure Gateway destination. This will be reachable from any system with access to the Internet and is best suited to development and testing, and not production use.
You can develop the application locally on the host, instead of within the vagrant vm without going out to the cloud endpoint. The Vagrantfile maps the local port 3000 to the Composer REST server. This allows you to use the http://localhost:8080/
endpoint when developing your application locally. When deploying to the cloud (as a CF runtime, or container) switch the endpoing to the cloud url (like http://cap-sg-prd-2.integration.ibmcloud.com:17870/
).