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.
Developers who want to get a fast start in developing a blockchain solution can quickly begin by using Hyperledger Composer on a local development system. After a business network is created and deployed locally, it’s also possible to deploy a REST server that exposes the business network for easy access by a front-end application.
But what happens when the target front-end application is for a mobile system or is running on a cloud runtime environment, such as a Cloud Foundry application or a Docker container, and the app needs to access the local blockchain business network? Or in general, you might be looking for a way to establish a connection to a network service that is running on a host that has outbound internet access, but it doesn’t support inbound access. The network service might be behind a firewall or on a dynamic IP address.
You can solve these problems by creating an internet-based proxy that accepts network connections and then forwards them to the service of interest. In this tutorial, you learn how to create this proxy for a Hyperledger Composer REST server by using the IBM Secure Gateway service.
Complete this tutorial to understand how to create a REST server for a Blockchain business network and how to make it available on the internet. The tutorial shows how to configure a simple business network using Hyperledger Composer running on a local virtual machine. Then, you use the IBM Secure Gateway service to provide an internet-reachable network service that proxies connections to the REST server on the virtual machine.
To complete this tutorial, you need:
This tutorial does not cover the development of blockchain business networks using Hyperledger Composer. For more information about developing those blockchain business networks, see the Hyperledger Composer tutorials.
The steps in this tutorial take about 30-45 minutes to complete. Add time to create the desired business network, if you are creating one from scratch.
Complete the following steps to create a local virtual machine (VM) that is capable of serving a Composer Business Network as a REST API endpoint. First, you use Vagrant to configure a VM with Docker support. After the VM is configured, continue by following the Hyperledger Composer set-up steps for a local envionment at Installing the development environment. Finally, after you have the local Composer REST server running locally, configure a Secure Gateway instance to expose the API on the IBM Cloud.
Configure a VM with Docker support
Create a directory for the project:
Copy the contents of the Vagrantfile into the directory.
Start the Vagrant image from the directory (this might take a little while):
After the VM is up, log in to start configuring Hyperledger Fabric:
Set up Hyperledger Composer
Follow the pre-requisite setup steps for a local Hyperledger Composer environment for Ubuntu at Installing prerequisites. Complete these steps as an ordinary user and not a root user on the VM. Log out from vagrant with
exitand reconnect with
vagrant sshwhen prompted.
curl -O https://hyperledger.github.io/composer/latest/prereqs-ubuntu.sh chmod u+x prereqs-ubuntu.sh ./prereqs-ubuntu.sh
After you finish installing pre-requisites, set up the Hyperledger Fabric local development environment as described at Installing the development environment, starting with the CLI tools.
npm install -g firstname.lastname@example.org npm install -g email@example.com npm install -g firstname.lastname@example.org npm install -g yo
Install Composer Playground.
npm install -g email@example.com
Optional: Follow steps to set up IDE Step 3 of Installing the development environment.
Complete Step 4 from the set-up instructions 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
Proceed with the steps under “Controlling your dev environment” to start the development fabric and create the PeerAdmin card:
cd ~/fabric-dev-servers export FABRIC_VERSION=hlfv12 ./startFabric.sh ./createPeerAdminCard.sh
Start the web app for Composer (“Playground”). Note: Starting the web app does not start up a browser session automatically as described in the documentation, because the command is running inside the VM instead of on the workstation.
After the service starts, navigate with a browser tab to
http://localhost:8080/(this local port is mapped by the
Vagrantfileconfiguration to the VM).
Develop a business network and test in the Composer Playground as usual. If you’ve never used composer playground, the Playground Tutorial is a good place to start.
After you have completed testing the intended business network, deploy the Composer REST server, providing the card for the network owner (
admin@marbles-networkin this example). See Step 5 from Developer tutorial for creating a Hyperledger Composer solution for explanations on the responses to the input prompts. The Secure Gateway connectivity steps in this tutorial were tested with the following 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
Keep the REST server running in the terminal. When finished with the REST API server, you can use Ctrl-C in the terminal to terminate the server.
Test the REST API server by opening
http://localhost:3000/explorerin a browser.
Configure a Secure Gateway instance to expose the API on the cloud
Open the IBM Cloud catalog entry for Secure Gateway to create a Secure Gateway instance in your IBM Cloud account. You 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. Verify that this plan is selected, and click on Create.
Click Add Gateway in the Secure Gateway Service Details panel. Enter a name in the panel, for example: “Blockchain”. Keep the other gateway default settings of Requre security token to connect clients and Token expriation before 90 days. Click othe Add Gateway button to create the gateway.
Click the Connect Client button on the Secure Gateway Service Details panel to begin setting up the client that runs on the VM and connect to the Secure Gateway service.
Choose Docker as the option to connect the client and copy the provided
docker runcommand with the Gateway id and security token.
Open a new local terminal window, change directory to the folder with the
Vagrantfileand then connect to the VM using
vagrant ssh. Paste the
docker runcommand shown into this terminal to start the Secure Gateway client and leave a CLI running in the terminal. Do not close this terminal. After the container starts, you see messages like the following example, 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>
After the client has started, close the web ui panel to display the Secure Gateway service details.
On another terminal on the vagrant VM, use the
ip address showcommand to find the IP address of the VM. Many interfaces are listed. Select the one that begins with
eth. In the examples that follow, the VM IP address is
Return to the terminal for the Secure Gateway client docker container, create an acl entry that allows traffic to the composer REST API server running on port 3000.
acl allow 10.0.2.15:3000 1
Define a basic http connection through the Secure Gateway service to the Composer REST API server. For more advanced security settings refer to the Secure Gateway documentation. Click on the Destinations tab in the Secure Gateway service details. Next, click on the “+” icon to open the Add Destination 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 serverfor 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 – which looks something like:
cap-sg-prd-2.integration.ibmcloud.com:17870. This host and port is the Cloud endpoint that can be accessed. Traffic is forwarded by the Secure Gateway service to the running Composer REST server.
/explorerafter the host and port and open this url in a web browser. For the example, the final url would be:
At this point you should be able to access the Composer REST server to perform actions in the deployed business network, using the host name and the port from the Secure Gateway destination. This server is 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 mapping allows you to use the
http://localhost:8080/ endpoint when developing your application locally. When deploying to the cloud (as a Cloud Foundry application, or Docker container) switch the endpoint to the cloud URL (for example
The Hyperledger Composer can generate a basic Angular interface to the business network. This step is described in Writing Web Applications.
To see how to deploy this Angular application to Cloud Foundry using DevOps, check out the Continuously deploy your Angular application tutorial. There are two changes to the tutorial for the generated Angular application. First, use the full project contents by leaving the Build Archive Directory empty in the Delivery Pipeline Build stage. Second, the application reads the REST API server endpoint from the environment, set this in the Delivery Pipeline Deploy stage by adding an environment property of
REST_SERVER_URL with a value of the cloud URL.