Skip to content

Commit

Permalink
NodeSDK doc changes -- FAB-146
Browse files Browse the repository at this point in the history 
     Changes:
        modified:   docs/Setup/NodeSDK-setup.md
        modified:   docs/index.md
        new file:   docs/nodeSDK/app-developer-env-setup.md
        new file:   docs/nodeSDK/app-overview.md
        new file:   docs/nodeSDK/node-sdk-guide.md
        new file:   docs/nodeSDK/node-sdk-indepth.md
        new file:   docs/nodeSDK/node-sdk-self-contained.md
        new file:   docs/nodeSDK/sample-standalone-app.md
        new file:   docs/nodeSDK/sample-web-app.md
        new sample file:   examples/sdk/node/standalone-app.js
        new sample file:   examples/sdk/node/web-app.js

Change-Id: I65f0f470806bc66a28d151780e1f36cf05b509df
Signed-off-by: Bret Harrison <beharrison@nc.rr.com>
  • Loading branch information
@harrisob
harrisob committed Sep 14, 2016
1 parent 9bf95d0 commit 8de58ed
Show file tree
Hide file tree
Showing 11 changed files with 856 additions and 307 deletions.
311 changes: 5 additions & 306 deletions docs/Setup/NodeSDK-setup.md
100644 → 100755
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,312 +18,11 @@ execute the following command:
npm install -g hfc
```

## Overview
See [Hyperledger fabric Node.js client SDK](../nodeSDK/node-sdk-guide.md) for more information.

The sections in this document are as follows:

* The [Getting Started](#getting-started) section is intended to help you
quickly get a feel for HFC, how to use it, and some of its common capabilities.
This is demonstrated by example.
## Hyperledger fabric network

* The [Getting Set Up](#getting-set-up) section shows you how to set up up your
environment and how to [run the unit tests](#running-unit-tests). Looking at the
implementation of the unit tests will also help you learn more about the APIs by
example, including asset management and confidentiality.

## Getting Started
This purpose of this section is to help you quickly get a feel for HFC and how
you may use it. It is not intended to demonstrate all of its power, but to
demonstrate common use cases by example.

### Some basic terminology
First, there is some basic terminology you should understand. In order to
transact on a hyperledger blockchain, you must first have an identity which has
been both **registered** and **enrolled**.

Think of **registration** as *issuing a user invitation* to join a blockchain.
It consists of adding a new user name (also called an *enrollment ID*) to the
membership service configuration. This can be done programatically with the
`Member.register` method, or by adding the enrollment ID directly to the
[membersrvc.yaml](https://github.com/hyperledger/fabric/blob/master/membersrvc/membersrvc.yaml)
configuration file.

Think of **enrollment** as *accepting a user invitation* to join a blockchain.
This is always done by the entity that will transact on the blockchain. This can
be done programatically via the `Member.enroll` method.

### Learn by example
The best way to quickly learn HFC is by example.

The following example demonstrates a typical web app. The web app authenticates
a user and then transacts on a blockchain on behalf of that user.

```
/**
* This example shows how to do the following in a web app.
* 1) At initialization time, enroll the web app with the block chain.
* The identity must have already been registered.
* 2) At run time, after a user has authenticated with the web app:
* a) register and enroll an identity for the user;
* b) use this identity to deploy, query, and invoke a chaincode.
*/
// To include the package from your hyperledger fabric directory:
// var hfc = require("myFabricDir/sdk/node");
// To include the package from npm:
// var hfc = require('hfc');
var hfc = require('hfc');
// Create a client chain.
// The name can be anything as it is only used internally.
var chain = hfc.newChain("targetChain");
// Configure the KeyValStore which is used to store sensitive keys
// as so it is important to secure this storage.
// The FileKeyValStore is a simple file-based KeyValStore, but you
// can easily implement your own to store whereever you want.
chain.setKeyValStore( hfc.newFileKeyValStore('/tmp/keyValStore') );
// Set the URL for member services
chain.setMemberServicesUrl("grpc://localhost:7054");
// Add a peer's URL
chain.addPeer("grpc://localhost:7051");
// Enroll "WebAppAdmin" which is already registered because it is
// listed in fabric/membersrvc/membersrvc.yaml with its one time password.
// If "WebAppAdmin" has already been registered, this will still succeed
// because it stores the state in the KeyValStore
// (i.e. in '/tmp/keyValStore' in this sample).
chain.enroll("WebAppAdmin", "DJY27pEnl16d", function(err, webAppAdmin) {
if (err) return console.log("ERROR: failed to register %s: %s",err);
// Successfully enrolled WebAppAdmin during initialization.
// Set this user as the chain's registrar which is authorized to register other users.
chain.setRegistrar(webAppAdmin);
// Now begin listening for web app requests
listenForUserRequests();
});
// Main web app function to listen for and handle requests
function listenForUserRequests() {
for (;;) {
// WebApp-specific logic goes here to await the next request.
// ...
// Assume that we received a request from an authenticated user
// 'userName', and determined that we need to invoke the chaincode
// with 'chaincodeID' and function named 'fcn' with arguments 'args'.
handleUserRequest(userName,chaincodeID,fcn,args);
}
}
// Handle a user request
function handleUserRequest(userName, chaincodeID, fcn, args) {
// Register and enroll this user.
// If this user has already been registered and/or enrolled, this will
// still succeed because the state is kept in the KeyValStore
// (i.e. in '/tmp/keyValStore' in this sample).
// The attributes field is optional but can be used for role-based access control.
// See fabric/sdk/node/test/unit/asset-mgmt-with-dynamic-roles.js as an example.
var registrationRequest = {
enrollmentID: userName,
// Customize account & affiliation
account: "bank_a",
affiliation: "00001",
attributes: [
{ name: "bankAccountId", value: "12345-67890" }
]
};
chain.registerAndEnroll( registrationRequest, function(err, user) {
if (err) return console.log("ERROR: %s",err);
// Issue an invoke request
var invokeRequest = {
// Name (hash) required for invoke
chaincodeID: chaincodeID,
// Function to trigger
fcn: fcn,
// Parameters for the invoke function
args: args
};
// Invoke the request from the user object.
var tx = user.invoke(invokeRequest);
// Listen for the 'submitted' event
tx.on('submitted', function(results) {
console.log("submitted invoke: %j",results);
});
// Listen for the 'complete' event.
tx.on('complete', function(results) {
console.log("completed invoke: %j",results);
});
// Listen for the 'error' event.
tx.on('error', function(err) {
console.log("error on invoke: %j",err);
});
});
}
```

## Getting Set Up

First, you'll want to have a running peer node and CA. You can follow the
instructions for setting up a network
[here](https://github.com/hyperledger/fabric/blob/master/docs/Setup/ca-setup.md#Operating-the-CA),
and start a single peer node and CA.

### Chaincode Deployment Directory Structure

To have the chaincode deployment succeed in network mode, you must properly set
up the chaincode project outside of your Hyperledger Fabric source tree. The
following instructions will demonstrate how to properly set up the directory
structure to deploy *chaincode_example02* in network mode.

The chaincode project must be placed under the `$GOPATH/src` directory. For
example, the
[chaincode_example02](https://github.com/hyperledger/fabric/blob/master/examples/chaincode/go/chaincode_example02/chaincode_example02.go)
project should be placed under `$GOPATH/src/` as shown below.

```
mkdir -p $GOPATH/src/github.com/chaincode_example02/
cd $GOPATH/src/github.com/chaincode_example02
curl GET https://raw.githubusercontent.com/hyperledger/fabric/master/examples/chaincode/go/chaincode_example02/chaincode_example02.go > chaincode_example02.go
```

After you have placed your chaincode project under the `$GOPATH/src`, you will need to vendor the dependencies. From the directory containing your chaincode source, run the following commands:

```
go get -u github.com/kardianos/govendor
cd $GOPATH/src/github.com/chaincode_example02
govendor init
govendor fetch github.com/hyperledger/fabric
```

Now, execute `go build` to verify that all of the chaincode dependencies are
present.

```
go build
```

Next, we will switch over to the node sdk directory in the fabric repo to run
the node sdk tests, to make sure you have everything properly set up. Verify
that the
[chain-tests.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/chain-tests.js)
unit test file points to the correct chaincode project path. The default
directory is set to `github.com/chaincode_example02/` as shown below. If you
placed the sample chaincode elsewhere, then you will need to change that.

```
// Path to the local directory containing the chaincode project under $GOPATH
var testChaincodePath = "github.com/chaincode_example02/";
```

**Note:** You will need to run `npm install` the first time you run the sdk
tests, in order to install all of the dependencies. Set the `DEPLOY_MODE`
environment variable to `net` and run the chain-tests as follows:

```
cd $GOPATH/src/github.com/hyperledger/fabric/sdk/node
npm install
export DEPLOY_MODE='net'
node test/unit/chain-tests.js | node_modules/.bin/tap-spec
```

### Enabling TLS

If you wish to configure TLS with the Membership Services server, the following
steps are required:

- Modify `$GOPATH/src/github.com/hyperledger/fabric/membersrvc/membersrvc.yaml` as follows:

```
server:
tls:
cert:
file: "/var/hyperledger/production/.membersrvc/tlsca.cert"
key:
file: "/var/hyperledger/production/.membersrvc/tlsca.priv"
```

To specify to the Membership Services (TLS) Certificate Authority (TLSCA) what
X.509 v3 Certificate (with a corresponding Private Key) to use:

- Modify `$GOPATH/src/github.com/hyperledger/fabric/peer/core.yaml` as follows:

```
peer:
pki:
tls:
enabled: true
rootcert:
file: "/var/hyperledger/production/.membersrvc/tlsca.cert"
```

To configure the peer to connect to the Membership Services server over TLS
(otherwise, the connection will fail).

- Bootstrap your Membership Services and the peer. This is needed in order to
have the file *tlsca.cert* generated by the member services.

- Copy `/var/hyperledger/production/.membersrvc/tlsca.cert` to
`$GOPATH/src/github.com/hyperledger/fabric/sdk/node`.

*Note:* If you cleanup the folder `/var/hyperledger/production` then don't
forget to copy again the *tlsca.cert* file as described above.

## Running Unit Tests
HFC includes a set of unit tests implemented with the
[tape framework](https://github.com/substack/tape). The
[unit test script](https://github.com/hyperledger/fabric/blob/master/sdk/node/bin/run-unit-tests.sh)
builds and runs both the membership service server and the peer node for you,
therefore you do not have to start those manually.

### Running the SDK unit tests
HFC includes a set of unit tests implemented with the
[tape framework](https://github.com/substack/tape). To run the unit tests,
execute the following commands:

cd $GOPATH/src/github.com/hyperledger/fabric
make node-sdk-unit-tests

The following are brief descriptions of each of the unit tests that are being
run.

#### registrar
The [registrar.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/registrar.js)
test case exercises registering users with Membership Services. It also tests
registering a designated registrar user which can then register additional users.

#### chain-tests
The [chain-tests.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/chain-tests.js)
test case exercises the [chaincode_example02.go](https://github.com/hyperledger/fabric/tree/master/examples/chaincode/go/chaincode_example02)
chaincode when it has been deployed in both development mode and network mode.

#### asset-mgmt
The [asset-mgmt.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/asset-mgmt.js)
test case exercises the [asset_management.go](https://github.com/hyperledger/fabric/tree/master/examples/chaincode/go/asset_management)
chaincode when it has been deployed in both development mode and network mode.

#### asset-mgmt-with-roles
The [asset-mgmt-with-roles.js](https://github.com/hyperledger/fabric/blob/master/sdk/node/test/unit/asset-mgmt-with-roles.js)
test case exercises the [asset_management_with_roles.go](https://github.com/hyperledger/fabric/tree/master/examples/chaincode/go/asset_management_with_roles)
chaincode when it has been deployed in both development mode and network mode.

#### Troublingshooting
If you see errors stating that the client has already been registered/enrolled,
keep in mind that you can perform the enrollment process only once, as the
enrollmentSecret is a one-time-use password. You will see these errors if you
have performed a user registration/enrollment and subsequently deleted the
cryptographic tokens stored on the client side. The next time you try to enroll,
errors similar to the ones below will be seen.

```
Error: identity or token do not match
```
```
Error: user is already registered
```

To address this, remove any stored cryptographic material from the CA server by
following the instructions [here](https://github.com/hyperledger/fabric/blob/master/docs/Setup/Chaincode-setup.md#removing-temporary-files-when-security-is-enabled).
You will also need to remove any of the cryptographic tokens stored on the
client side by deleting the KeyValStore directory. That directory is
configurable and is set to `/tmp/keyValStore` within the unit tests.
First, you'll want to have a running peer node and member services. The
instructions for setting up a network are
[here](Network-setup.md). You may also use the [self contained environment](../nodeSDK/node-sdk-self-contained.md) that provides the network.
2 changes: 1 addition & 1 deletion docs/index.md
100644 → 100755
View file
Original file line number Diff line number Diff line change
Expand Up @@ -157,7 +157,7 @@ relating to Chaincode.
- [APIs - CLI, REST, and Node.js](API/CoreAPI.md)
- [CLI](API/CoreAPI.md#cli): working with the command-line interface.
- [REST](API/CoreAPI.md#rest-api): working with the REST API.
- [Node.js SDK](https://github.com/hyperledger/fabric/blob/master/sdk/node/README.md): working with the Node.js SDK.
- [Node.js SDK](nodeSDK/node-sdk-guide.md): working with the Node.js SDK.

# Operations guide

Expand Down
33 changes: 33 additions & 0 deletions docs/nodeSDK/app-developer-env-setup.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Setting up the Full Hyperledger fabric Developer's Environment

1. See [Setting Up The Development Environment](../dev-setup/devenv.md) to set up your development environment.

2. Issue the following commands to build the Hyperledger fabric client (HFC) Node.js SDK including the API reference documentation

```
cd /opt/gopath/src/github.com/hyperledger/fabric/sdk/node
make all
```

3. Issue the following command where your Node.js application is located if you wish to use the `require("hfc")`, this will install the HFC locally.

```
npm install /opt/gopath/src/github.com/hyperledger/fabric/sdk/node
```

Or use point directly to the HFC directly by using the following require in your code:
```javascript
require("/opt/gopath/src/github.com/hyperledger/fabric/sdk/node");
```

4. To see the API reference documentation which is built in step 2:
```
cd /opt/gopath/src/github.com/hyperledger/fabric/sdk/node/doc
```

The [Self Contained Node.js Environment](node-sdk-self-contained.md) will have the reference documentation already built and may be accessed by:
```
docker exec -it nodesdk /bin/bash
cd /opt/gopath/src/github.com/hyperledger/fabric/sdk/node/doc
```
Loading

0 comments on commit 8de58ed

Please sign in to comment.