Taxonomy Icon

Hybrid Cloud

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.

Learning objectives

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.

Prerequisites

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.

Estimated time

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.

Steps

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

  1. Create a directory for the project:

    mkdir composer

  2. Copy the contents of the Vagrantfile into the directory.

  3. Start the Vagrant image from the directory (this might take a little while):

    vagrant up

  4. After the VM is up, log in to start configuring Hyperledger Fabric:

    vagrant ssh

Set up Hyperledger Composer

  1. 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 exit and reconnect with vagrant ssh when prompted.

    curl -O https://hyperledger.github.io/composer/latest/prereqs-ubuntu.sh chmod u+x prereqs-ubuntu.sh ./prereqs-ubuntu.sh

  2. 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 composer-cli@0.20 npm install -g composer-rest-server@0.20 npm install -g generator-hyperledger-composer@0.20 npm install -g yo

  3. Install Composer Playground.

    npm install -g composer-playground@0.20

  4. Optional: Follow steps to set up IDE Step 3 of Installing the development environment.

  5. 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

  6. 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

  7. 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.

    composer-playground

    After the service starts, navigate with a browser tab to http://localhost:8080/ (this local port is mapped by the Vagrantfile configuration to the VM).

  8. 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.

  9. After you have completed testing the intended business network, deploy the Composer REST server, providing the card for the network owner (admin@marbles-network in 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.

  10. Test the REST API server by opening http://localhost:3000/explorer in a browser.

Configure a Secure Gateway instance to expose the API on the cloud

  1. 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.

  2. 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.

  3. 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.

  4. Choose Docker as the option to connect the client and copy the provided docker run command with the Gateway id and security token.

  5. Open a new local terminal window, change directory to the folder with the Vagrantfile and then connect to the VM using vagrant ssh. Paste the docker run command 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.

  6. On another terminal on the vagrant VM, use the ip address show command to find the IP address of the VM. Many interfaces are listed. Select the one that begins with enp or eth. In the examples that follow, the VM IP address is 10.0.2.15.

  7. 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

  8. 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.

  9. For the “Where is your resource located?” item, select On-premises and then click on Next.

  10. 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.

  11. For the connection protocol, select HTTP and then click on Next.

  12. For the destination authentication, select None and then click on Next.

  13. 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.

  14. Enter a name like Composer REST server for the name of the destination and click on Add Destination

  15. 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.

  16. 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/ .

Summary

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 http://cap-sg-prd-2.integration.ibmcloud.com:17870/).

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.