Skip to content

Commit

Permalink
Updates to the node SDK docs and sample files
Browse files Browse the repository at this point in the history 
cherry-picking commit 70237c3.
Fix broken links and formatting issues on doc files
Include docker image and compose files to support docs
Update sample apps with environment settings
fix src and tag in dockerfile
fix docker image name in doc

Change-Id: I7e2781411199039ee851ec5da63d3f9377767cac
Signed-off-by: Bret Harrison <beharrison@nc.rr.com>
  • Loading branch information
@harrisob
harrisob committed Sep 22, 2016
1 parent d4d04e9 commit 463b148
Show file tree
Hide file tree
Showing 12 changed files with 458 additions and 499 deletions.
67 changes: 42 additions & 25 deletions docs/nodeSDK/app-developer-env-setup.md
View file
Original file line number Diff line number Diff line change
@@ -1,33 +1,50 @@
# 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.
* See [Setting Up The Development Environment](../dev-setup/devenv.md) to set up your development environment.

* The following commands are all issued from the vagrant environment. The following will open a terminal session:

2. Issue the following commands to build the Hyperledger fabric client (HFC) Node.js SDK including the API reference documentation
```
cd <your cloned location>/fabric/devenv
vagrant up
vagrant ssh
```

```
* 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
```
* 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 point 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:
```
```

* To build the API reference documentation:

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

* To build the reference documentation in the [Self Contained Node.js Environment](node-sdk-self-contained.md):

```
docker exec -it nodesdk /bin/bash
cd /opt/gopath/src/github.com/hyperledger/fabric/sdk/node/doc
```
cd /opt/gopath/src/github.com/hyperledger/fabric/sdk/node
make doc
```

* The the API reference documentation will be available in:
```
/opt/gopath/src/github.com/hyperledger/fabric/sdk/node/doc
```

28 changes: 15 additions & 13 deletions docs/nodeSDK/app-overview.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,18 @@

Hyperledger fabric supports two types of applications:

* A standalone application that interacts directly with a blockchain.
* A standalone application that interacts directly with a blockchain.
See the [Standalone Application](#standaloneApp) section.

* A web application that interacts with a blockchain on behalf of its web application users.
* A web application that interacts with a blockchain on behalf of its web application users.
See the [Web Application](#webApp) section.

<a name="standaloneApp"></a>
## Standalone Application

The following diagram provides an overview of the major components of Hyperledger fabric for the standalone application developer.

![Reference architecture](../images/standalone-app-developer.png)
<img src="../images/standalone-app-developer.png" width="900" height="456">

In the diagram above, the blue boxes are Hyperledger fabric components and the green boxes are application developer components. Each outer box represents a separate process.

Expand All @@ -24,31 +24,33 @@ The **Standalone Application** may be developed in Node.js by using the Hyperled

The **SDK** interacts with a **Peer** process. If the Peer process fails, the Node.js Client SDK can fail-over to another Peer as shown by the dotted line from the Node.js Client SDK to another Peer.

This interaction with the Peer consists of submitting transactions to the blockchain. There are three types of transactions:
* deploy - to deploy developer's chaincode as depicted by the green **CC1** boxes in the diagram;
* invoke - to execute a chaincode function which changes the state of the *blockchain database*;
This interaction with the Peer consists of submitting transactions to the blockchain. There are three types of transactions:

* deploy - to deploy developer's chaincode as depicted by the green **CC1** boxes in the diagram;
* invoke - to execute a chaincode function which changes the state of the *blockchain database*;
* query - to execute a chaincode function which may return state information related to the *blockchain database*.

The **SDK** also interacts with a **Membership Services** process. In fact, if security is enabled in the Peer (strongly recommended), the Node.js client SDK must interact with Membership Services first in order to retrieve *credentials* which are then used to interact with the Peer. These *credentials* consist of certificates as described in [Membership Services](membership-services.md).
The **SDK** also interacts with a **Membership Services** process. In fact, if security is enabled in the Peer (strongly recommended), the Node.js client SDK must interact with Membership Services first in order to retrieve credential certificates which are then used to interact with the Peer.

The interaction with the Membership Services consists of:
* register - to indicate a new user to the blockchain

* register - to invite a new user to the blockchain
* enroll - to get access to the blockchain

<a name="webApp"></a>
## Web Application

The following diagram provides an overview of the major components of Hyperledger fabric for the web application developer.

At a high-level, you can think of the Block Chain as a database with which the web application interacts; therefore, it is similar to the following topology.
At a high-level, you can think of the blockchain as a database with which the web application interacts; therefore, it is similar to the following topology.

```
browser --> web tier --> database tier
```
```

![Reference architecture](../images/web-app-developer.png)
<img src="../images/web-app-developer.png" width="900" height="456">

In the diagram above, the blue boxes are Hyperledger fabric components and the green boxes are application developer components. Each outer box represents a separate process.

The browser interacts with the developer's Node.js web application using the Hyperledger fabric's Node.js client SDK. The SDK handles all interactions with other Hyperledger fabric components in the same manor as described in the [SDK interactions](#sdk-interactions) section of [Standalone Application](#standaloneApp).

The browser interacts with the developer's Node.js web application using the Hyperledger fabric's Node.js client SDK. The SDK handles all interactions with other Hyperledger fabric components as described in the [SDK interactions](#sdk-interactions) section of [Standalone Application](#standaloneApp).
4 changes: 2 additions & 2 deletions docs/nodeSDK/node-sdk-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,12 +21,12 @@ The Hyperledger fabric Client (HFC) SDK for Node.js provides a powerful and easy

* [Node.js Standalone Application in Vagrant](sample-standalone-app.md) for a sample standalone Node.js application running in the full development environment within Vagrant.

* [Node.js Web Application](sample-web-app.md) for a sample web application and to see how to use the Node.js client SDK for a sample web app leveraging the client SDK to interact with blockchain network.
* [Node.js Web Application](sample-web-app.md) for a sample web application and to see how to use the Node.js client SDK for a sample web app leveraging the client SDK to interact with a blockchain network.



#### Related information

* To build and view the reference documentation for the Node.js client SDK APIs follow the instructions [here](app-developer-env-setup.md).
* To build the reference documentation for the Node.js client SDK APIs follow the instructions [here](app-developer-env-setup.md).

* To learn more about chaincode, see [Writing, Building, and Running Chaincode in a Development Environment](../Setup/Chaincode-setup.md).
89 changes: 50 additions & 39 deletions docs/nodeSDK/node-sdk-indepth.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,18 +2,29 @@

The Hyperledger fabric Client (HFC) SDK provides a powerful and easy to use API to interact with a Hyperledger fabric blockchain.

Below, you'll find the following sections:

- [Installing only the SDK](#installing-only-the-sdk)
- [Terminology](#terminology)
- [HFC Objects](#hfc-objects)
- [Pluggability](#pluggability)
- [Chaincode Deployment](#chaincode-deployment)
- [Enabling TLS](#enabling-tls)
- [Troubleshooting](#troubleshooting)

## Installing only the SDK

If you are an experienced node.js developer and already have a blockchain environment set up and running elsewhere, you can set up a client-only environment to run the node.js client by installing the HFC node module as shown below. This assumes npm version 2.11.3 and node.js version 0.12.7 are already installed.
If you are an experienced node.js developer and already have a blockchain environment set up and running elsewhere, you can set up a client-only environment to run the node.js client by installing the HFC node module as shown below. This assumes a minimum of npm version 2.11.3 and node.js version 0.12.7 are already installed.

* To install the latest HFC module of Hyperledger fabric

```
npm install hfc
npm install hfc
```

### Terminology

In order to transact on a hyperledger blockchain, you must first have an identity which has been both **registered** and **enrolled** with Membership Services. For a topological overview of how the components interact, see [Application Developer's Overview](app-developer-overview.md).
In order to transact on a Hyperledger fabric blockchain, you must first have an identity which has been both **registered** and **enrolled** with Membership Services. For a topological overview of how the components interact, see [Application Developer's Overview](app-overview.md).

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.

Expand Down Expand Up @@ -45,58 +56,59 @@ The following is a high-level description of the HFC objects (classes and interf

This class implements the bulk of the deploy, invoke, and query logic. It interacts with Membership Services to get a TCert to perform these operations. Note that there is a one-to-one relationship between TCert and TransactionContext. In other words, a single TransactionContext will always use the same TCert. If you want to issue multiple transactions with the same TCert, then you can get a `TransactionContext` object from a `Member` object directly and issue multiple deploy, invoke, or query operations on it. Note however that if you do this, these transactions are linkable, which means someone could tell that they came from the same user, though not know which user. For this reason, you will typically just call deploy, invoke, and query on the Member or User object.

#### Pluggability
## Pluggability

HFC was designed to support two pluggable components:

1. Pluggable `KeyValStore` key value store which is used to retrieve and store keys associated with a member. The key value store is used to store sensitive private keys, so care must be taken to properly protect access.
1. Pluggable `KeyValStore` key value store which is used to retrieve and store keys associated with a member. The key value store is used to store sensitive private keys, so care must be taken to properly protect access.

**IMPORTANT NOTE**: The default KeyValStore is file-based. If multiple instances of a web application run in a cluster, you must provide an implementation of the KeyValStore which is used by all members of the cluster.

2. Pluggable `MemberServices` which is used to register and enroll members. Member services enables hyperledger to be a permissioned blockchain, providing security services such as anonymity, unlinkability of transactions, and confidentiality

### Chaincode Deployment
## Chaincode Deployment

#### 'net' mode
### 'net' mode

To have the chaincode deployment succeed in network mode, you must properly set
up the chaincode project outside of your Hyperledger fabric source tree to include all the **golang** dependencies such that when tarred up and sent to the peer, the peer will be able to build the chain code and then deploy it. 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)
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
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
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
go build
```

#### 'dev' mode
### 'dev' mode
For deploying chaincode in development mode see [Writing, Building, and Running Chaincode in a Development Environment](../Setup/Chaincode-setup.md).
The chaincode must be running and connected to the peer before issuing the `deploy()` from the Node.js application. The hfc `chain` object must be set to dev mode.

```javascript
chain.setDevMode(true);
```
The deploy request must include the `chaincodeName` that the chaincode registered with the peer. The built-in chaincode example checks an environment variable `CORE_CHAINCODE_ID_NAME=mycc` when it starts.

```json
var deployRequest = {
chaincodeName: 'mycc',
Expand All @@ -112,11 +124,11 @@ If you wish to configure TLS with the Membership Services server, the following
- Modify `$GOPATH/src/github.com/hyperledger/fabric/membersrvc/membersrvc.yaml` as follows:

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

Expand All @@ -125,12 +137,12 @@ To specify to the Membership Services (TLS) Certificate Authority (TLSCA) what X
- 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"
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).
Expand All @@ -140,19 +152,18 @@ To configure the peer to connect to the Membership Services server over TLS (oth
- 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.





### Troublingshooting
### Troubleshooting
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.
Loading

0 comments on commit 463b148

Please sign in to comment.