You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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>
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.
19
19
@@ -24,31 +24,33 @@ The **Standalone Application** may be developed in Node.js by using the Hyperled
24
24
25
25
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.
26
26
27
-
This interaction with the Peer consists of submitting transactions to the blockchain. There are three types of transactions:
28
-
* deploy - to deploy developer's chaincode as depicted by the green **CC1** boxes in the diagram;
29
-
* invoke - to execute a chaincode function which changes the state of the *blockchain database*;
27
+
This interaction with the Peer consists of submitting transactions to the blockchain. There are three types of transactions:
28
+
29
+
* deploy - to deploy developer's chaincode as depicted by the green **CC1** boxes in the diagram;
30
+
* invoke - to execute a chaincode function which changes the state of the *blockchain database*;
30
31
* query - to execute a chaincode function which may return state information related to the *blockchain database*.
31
32
32
-
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).
33
+
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.
33
34
34
35
The interaction with the Membership Services consists of:
35
-
* register - to indicate a new user to the blockchain
36
+
37
+
* register - to invite a new user to the blockchain
36
38
* enroll - to get access to the blockchain
37
39
38
40
<aname="webApp"></a>
39
41
## Web Application
40
42
41
43
The following diagram provides an overview of the major components of Hyperledger fabric for the web application developer.
42
44
43
-
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.
45
+
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.
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.
52
55
53
-
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).
54
-
56
+
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).
Copy file name to clipboardexpand all lines: docs/nodeSDK/node-sdk-guide.md
+2-2
Original file line number
Diff line number
Diff line change
@@ -21,12 +21,12 @@ The Hyperledger fabric Client (HFC) SDK for Node.js provides a powerful and easy
21
21
22
22
*[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.
23
23
24
-
*[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.
24
+
*[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.
25
25
26
26
27
27
28
28
#### Related information
29
29
30
-
* To build and view the reference documentation for the Node.js client SDK APIs follow the instructions [here](app-developer-env-setup.md).
30
+
* To build the reference documentation for the Node.js client SDK APIs follow the instructions [here](app-developer-env-setup.md).
31
31
32
32
* To learn more about chaincode, see [Writing, Building, and Running Chaincode in a Development Environment](../Setup/Chaincode-setup.md).
Copy file name to clipboardexpand all lines: docs/nodeSDK/node-sdk-indepth.md
+50-39
Original file line number
Diff line number
Diff line change
@@ -2,18 +2,29 @@
2
2
3
3
The Hyperledger fabric Client (HFC) SDK provides a powerful and easy to use API to interact with a Hyperledger fabric blockchain.
4
4
5
+
Below, you'll find the following sections:
6
+
7
+
-[Installing only the SDK](#installing-only-the-sdk)
8
+
-[Terminology](#terminology)
9
+
-[HFC Objects](#hfc-objects)
10
+
-[Pluggability](#pluggability)
11
+
-[Chaincode Deployment](#chaincode-deployment)
12
+
-[Enabling TLS](#enabling-tls)
13
+
-[Troubleshooting](#troubleshooting)
14
+
5
15
## Installing only the SDK
6
16
7
-
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.
8
-
17
+
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.
18
+
9
19
* To install the latest HFC module of Hyperledger fabric
20
+
10
21
```
11
-
npm install hfc
22
+
npm install hfc
12
23
```
13
24
14
25
### Terminology
15
26
16
-
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).
27
+
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).
17
28
18
29
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.
19
30
@@ -45,58 +56,59 @@ The following is a high-level description of the HFC objects (classes and interf
45
56
46
57
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.
47
58
48
-
####Pluggability
59
+
## Pluggability
49
60
50
61
HFC was designed to support two pluggable components:
51
62
52
-
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.
63
+
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.
64
+
53
65
**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.
54
66
55
67
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
56
68
57
-
###Chaincode Deployment
69
+
## Chaincode Deployment
58
70
59
-
####'net' mode
71
+
### 'net' mode
60
72
61
73
To have the chaincode deployment succeed in network mode, you must properly set
62
74
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
63
75
following instructions will demonstrate how to properly set up the directory
64
76
structure to deploy *chaincode_example02* in network mode.
65
77
66
-
The chaincode project must be placed under the `$GOPATH/src` directory. For
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)
69
79
project should be placed under `$GOPATH/src/` as shown below.
curl GET https://raw.githubusercontent.com/hyperledger/fabric/master/examples/chaincode/go/chaincode_example02/chaincode_example02.go > chaincode_example02.go
75
85
```
76
86
77
87
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:
78
88
79
89
```
80
-
go get -u github.com/kardianos/govendor
81
-
cd $GOPATH/src/github.com/chaincode_example02
82
-
govendor init
83
-
govendor fetch github.com/hyperledger/fabric
90
+
go get -u github.com/kardianos/govendor
91
+
cd $GOPATH/src/github.com/chaincode_example02
92
+
govendor init
93
+
govendor fetch github.com/hyperledger/fabric
84
94
```
85
95
86
96
Now, execute `go build` to verify that all of the chaincode dependencies are
87
97
present.
88
98
89
99
```
90
-
go build
100
+
go build
91
101
```
92
102
93
-
####'dev' mode
103
+
### 'dev' mode
94
104
For deploying chaincode in development mode see [Writing, Building, and Running Chaincode in a Development Environment](../Setup/Chaincode-setup.md).
95
105
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.
106
+
96
107
```javascript
97
108
chain.setDevMode(true);
98
109
```
99
110
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.
111
+
100
112
```json
101
113
var deployRequest = {
102
114
chaincodeName: 'mycc',
@@ -112,11 +124,11 @@ If you wish to configure TLS with the Membership Services server, the following
112
124
- Modify `$GOPATH/src/github.com/hyperledger/fabric/membersrvc/membersrvc.yaml` as follows:
To configure the peer to connect to the Membership Services server over TLS (otherwise, the connection will fail).
@@ -140,19 +152,18 @@ To configure the peer to connect to the Membership Services server over TLS (oth
140
152
- Copy `/var/hyperledger/production/.membersrvc/tlsca.cert` to `$GOPATH/src/github.com/hyperledger/fabric/sdk/node`.
141
153
142
154
*Note:* If you cleanup the folder `/var/hyperledger/production` then don't forget to copy again the *tlsca.cert* file as described above.
143
-
144
-
145
-
146
155
147
-
148
-
### Troublingshooting
156
+
### Troubleshooting
149
157
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.
150
158
151
-
```
159
+
```
152
160
Error: identity or token do not match
153
-
```
154
-
```
161
+
162
+
```
163
+
164
+
```
155
165
Error: user is already registered
156
-
```
166
+
167
+
```
157
168
158
169
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.
The docker compose environment uses three docker images. If you wish to customize and build your own docker images. The following [Dockerfile](https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/Dockerfile)
19
+
was used to build the **nodesdk** image and may be used as a starting point to your own customizations.
* Start the fabric network environment using docker-compose. From a terminal session that has the working directory of where the above *docker-compose.yml* is located, execute one of following **docker-compose** commands.
26
+
27
+
* to run as detached containers:
28
+
```
29
+
docker-compose up -d
30
+
```
31
+
**note:** to see the logs for the **peer** container use the `docker logs peer` command
32
+
33
+
* to run in the foreground and see the log output in the current terminal session:
34
+
```
35
+
docker-compose up
36
+
```
37
+
38
+
Both commands will start three docker containers, to view the container status try `docker ps` command. The first time this is run the **docker** images will be downloaded. This may take 10 minutes or more depending on the network connections of the system running the command.
39
+
```
40
+
docker ps
16
41
```
17
42
18
-
docker-compose.yml:
19
-
```yaml
20
-
membersrvc:
21
-
# try 'docker ps' to see the container status after starting this compose
22
-
container_name: membersrvc
23
-
image: hyperledger/fabric-membersrvc
24
-
command: membersrvc
25
-
26
-
peer:
27
-
container_name: peer
28
-
image: hyperledger/fabric-peer
29
-
environment:
30
-
- CORE_PEER_ADDRESSAUTODETECT=true
31
-
- CORE_VM_ENDPOINT=unix:///var/run/docker.sock
32
-
- CORE_LOGGING_LEVEL=DEBUG
33
-
- CORE_PEER_ID=vp0
34
-
- CORE_SECURITY_ENABLED=true
35
-
- CORE_PEER_PKI_ECA_PADDR=membersrvc:7054
36
-
- CORE_PEER_PKI_TCA_PADDR=membersrvc:7054
37
-
- CORE_PEER_PKI_TLSCA_PADDR=membersrvc:7054
38
-
- CORE_PEER_VALIDATOR_CONSENSUS_PLUGIN=noops
39
-
# this gives access to the docker host daemon to deploy chaincode in network mode
40
-
volumes:
41
-
- /var/run/docker.sock:/var/run/docker.sock
42
-
# have the peer wait 10 sec for membersrvc to start
43
-
# the following is to run the peer in Developer mode - also set sample DEPLOY_MODE=dev
44
-
command: sh -c "sleep 10; peer node start --peer-chaincodedev"
# set DEPLOY_MODE to 'dev' if peer running in Developer mode
60
-
- DEPLOY_MODE=dev
61
-
- CORE_CHAINCODE_ID_NAME=mycc
62
-
- CORE_PEER_ADDRESS=peer:7051
63
-
# the following command will start the chaincode when this container starts and ready it for deployment by the app
64
-
command: sh -c "sleep 20; /opt/gopath/src/github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02/chaincode_example02"
65
-
stdin_open: true
66
-
tty: true
67
-
links:
68
-
- membersrvc
69
-
- peer
70
-
43
+
You should see something like the following:
44
+
```
45
+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
46
+
bb01a2fa96ef hyperledger/fabric-node-sdk "sh -c 'sleep 20; /op" About a minute ago Up 59 seconds nodesdk
47
+
ec7572e65f12 hyperledger/fabric-peer "sh -c 'sleep 10; pee" About a minute ago Up About a minute peer
48
+
118ef6da1709 hyperledger/fabric-membersrvc "membersrvc" About a minute ago Up About a minute membersrvc
71
49
```
72
50
73
-
3. Start the fabric environment using docker-compose. From a terminal session where the working directory is where the *docker-compose.yml* from step 2 is located, execute one of following **docker-compose** commands.
51
+
* Start a terminal session in the **nodesdk** container. This is where the Node.js application is located.
74
52
75
-
* to run as detached containers, then to see the logs for the **peer** container use the `docker logs peer` command
76
-
```
77
-
docker-compose up -d
78
-
```
79
-
* to run in the foreground and see the log output in the current terminal session
80
-
```
81
-
docker-compose up
82
-
```
83
-
84
-
This will start three docker containers, to view the container status try `docker ps` command. The first time this is run the **docker** images will be downloaded. This may take 10 minutes or more depending on the network connections of the system running the command.
85
-
* Membership services --**membersrvc**
86
-
* Peer -- **peer**
87
-
* Node.js SDK Application and chaincode -- **nodesdk**
88
-
89
-
4. Start a terminal session in the **nodesdk** container. This is where the Node.js application is located.
53
+
**note:** Be sure to wait 20 seconds after starting the network using the `docker-compose up` command before executing the following command to allow the network to initialize.
90
54
91
-
**Note:** Be sure to wait 20 seconds after starting the network before executing.
92
-
93
-
```
55
+
```
94
56
docker exec -it nodesdk /bin/bash
95
-
```
57
+
```
96
58
97
-
5. From the terminal session in the **nodesdk** container execute the standalone Node.js application. The docker terminal session should be in the working directory of the sample application called **app.js** (*/opt/gopath/src/github.com/hyperledger/fabric/examples/sdk/node/example02*). Execute the following Node.js command to run the application.
59
+
* From the terminal session in the **nodesdk** container execute the standalone Node.js application. The docker terminal session should be in the working directory of the sample application called **app.js** (*/opt/gopath/src/github.com/hyperledger/fabric/examples/sdk/node*). Execute the following Node.js command to run the application.
98
60
99
-
```
61
+
```
100
62
node app
101
-
```
102
-
On another terminal session on the host you can view the logs for the peer by executing the following command (not in the docker shell above, in a new terminal session of the real system)
103
-
```
63
+
```
64
+
In another terminal session on the host you can view the logs for the peer by executing the following command (not in the docker shell above, in a new terminal session of the real system)
65
+
```
104
66
docker logs peer
105
-
```
106
-
107
-
6. This environment will have the reference documentation already built and may be access by:
108
-
```
109
-
docker exec -it nodesdk /bin/bash
110
-
cd /opt/gopath/src/github.com/hyperledger/fabric/sdk/node/doc
111
-
```
112
-
113
-
7. If you wish to run your own Node.js application
114
-
* use the directories in the `volumes` tag under **nodesdk** in the `docker-compose.yml` file as a place to store your programs from the host system into the docker container. The first path is the top level system (host system) and the second is created in the docker container. If you wish to use a host location that is not under the `/Users` directory (`~` is under `/Users') then you must add that to the **docker** file sharing under **docker** preferences.
115
-
```yaml
67
+
```
68
+
69
+
* If you wish to run your own Node.js application using the pre build docker images:
70
+
* use the directories in the `volumes` tag under **nodesdk** in the `docker-compose.yml` file as a place to store your programs from the host system into the docker container. The first path is the top level system (host system) and the second is created in the docker container. If you wish to use a host location that is not under the `/Users` directory (`~` is under `/Users') then you must add that to the **docker** file sharing under **docker** preferences.
71
+
72
+
```yaml
116
73
volumes:
117
74
- ~/mytest:/user/mytest
118
-
```
75
+
```
119
76
* copy or create and edit your application in the `~/mytest` directory as stated in the `docker-compose.yml``volumes` tag under **nodesdk** container.
120
77
* run npm to install Hyperledger Fabric Node.js SDK in the `mytest` directory
* run the application from within the **nodesdk** docker container using the commands
125
-
```
82
+
```
126
83
docker exec -it nodesdk /bin/bash
127
-
```
84
+
```
128
85
once in the shell, and assuming your Node.js application is called `app.js`
129
-
```
86
+
```
130
87
cd /user/mytest
131
88
node app
132
-
```
89
+
```
90
+
* To shutdown the environment, execute the following **docker-compose** command in the directory where the *docker-compose.yml* is located. Any changes you made to the sample application or deployment of a chaincode will be lost. Only changes made to the shared area defined in the 'volumes' tag of the **nodesdk** container will persist. This will shutdown each of the containers and remove the containers from **docker**:
133
91
134
-
8. To shutdown the environment, execute the following **docker-compose** command in the directory where the *docker-compose.yml* is located. Any changes you made to the sample application or deployment of a chaincode will be lost. Only changes made to the shared area defined in the 'volumes' tag of the **nodesdk** container will persist. This will shutdown each of the containers and remove the containers from **docker**:
135
-
136
-
```
92
+
```
137
93
docker-compose down
138
-
```
139
-
94
+
```
140
95
or if you wish to keep your changes and just stop the containers, which will be restarted on the next `up` command
Copy file name to clipboardexpand all lines: docs/nodeSDK/sample-standalone-app.md
+25-110
Original file line number
Diff line number
Diff line change
@@ -2,133 +2,48 @@
2
2
3
3
This section describes how to run a sample standalone Node.js application which interacts with a Hyperledger fabric blockchain.
4
4
5
-
1. If you haven't already done so, see [Setting Up The Application Development Environment](app-developer-env-setup.md) to get your environment set up. The remaining steps assume that you are running **inside the vagrant environment**.
5
+
* If you haven't already done so, see [Setting Up The Application Development Environment](app-developer-env-setup.md) to get your environment set up. The remaining steps assume that you are running **inside the vagrant environment**.
6
6
7
-
2. Issue the following commands to build the Node.js Client SDK:
7
+
* Issue the following commands to build the Node.js Client SDK:
8
8
9
-
```
9
+
```
10
10
cd /opt/gopath/src/github.com/hyperledger/fabric
11
11
make node-sdk
12
-
```
12
+
```
13
13
14
-
3. Start the membership services and peer processes. We run the peer in dev mode for simplicity.
14
+
* Start the membership services and peer processes. We run the peer in dev mode for simplicity.
15
15
16
-
```
16
+
```
17
17
cd /opt/gopath/src/github.com/hyperledger/fabric/build/bin
5. Put the following sample app in a file named **app.js** in the */tmp* directory. Take a moment (now or later) to read the comments and code to begin to learn the Node.js Client SDK APIs.
30
+
* Put the following sample app in a file named **app.js** in the */tmp* directory. Take a moment (now or later) to read the comments and code to begin to learn the Node.js Client SDK APIs.
Copy file name to clipboardexpand all lines: docs/nodeSDK/sample-web-app.md
+3-102
Original file line number
Diff line number
Diff line change
@@ -4,109 +4,10 @@ The following is a web application template. It is NOT a complete program.
4
4
5
5
This template code demonstrates how to communicate with a blockchain from a Node.js web application. It does not show how to listen for incoming requests nor how to authenticate your web users as this is application specific. The code below is intended to demonstrate how to interact with a Hyperledger fabric blockchain from an existing web application.
6
6
7
-
You may retrieve the sample application file:
7
+
You may retrieve the [sample application](https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/web-app.js) file:
0 commit comments