diff --git a/docs/app-dev-env-setup.md b/docs/app-dev-env-setup.md new file mode 100755 index 0000000000..ddc3019d73 --- /dev/null +++ b/docs/app-dev-env-setup.md @@ -0,0 +1,67 @@ + +This tutorial describes how to prepare a development environment in order to build a business application to use a blockchain network based on Hyperledger Fabric. At a high level, a business application against a Hyperledger Fabric network is made up of two parts: chaincode that runs in the servers ([endorser](http://hyperledger-fabric.readthedocs.io/en/latest/arch-deep-dive.html#peer) nodes), and client code that runs in the client application. + +For chaincode development, please visit the tutorial [here](http://hyperledger-fabric.readthedocs.io/en/latest/FAQ/chaincode_FAQ.html#chaincode-smart-contracts-and-digital-assets). + +The following tutorial assumes a chaincode has been developed and the focus is developing the client application. + +## What makes up a Hyperledger Fabric application development environment? + +Below you'll find a high level summary of the Hyperledger Fabric design aimed at an introductory level of understanding, so that you can be on your way to setting up the development environment. For a comprehensive description of the concepts, the architecture, please visit the official [Hyperledger Fabric documentation](http://hyperledger-fabric.readthedocs.io/en/latest/overview.html). + +First of all, you will need an [orderer](http://hyperledger-fabric.readthedocs.io/en/latest/orderingservice.html). But isn't an orderer responsible for the consensus? Why start here? It's true that the main responsibility of the ordering service of a Hyperledger Fabric blockchain network is to provide consensus on a transaction among the maintainers of the ledger, a.k.a the committer nodes. However, the ordering service also maintains critical data about the overall network: what organizations are participating, what channels have been created, which organizations are part of a given channel, and last but not least what policies are in place for any kind of changes to the network. In essence, the ordering service holds the network together. + +Ok we've got to have an orderer node so we can add participating organizations to it and get a network started. Next you would need peers for each participating organization in order to participate in transaction endorsing and maintaining the ledger. + +The peer nodes play two roles: endorser and committer. A peer's endorser role may be enabled or disabled based on bootstrap configuration. But all peers are always committers. For high availability you would want more than one peer for each organization in a real deployment. But for the development environment, one peer per organization is sufficient under most circumstances. This peer will be both an endorse and a committer. It will be sent transaction proposals to endorse, and queries to discover information from the ledger. + +Another important role that peer nodes play is broadcasting events to interested parties. Whenever a block is added to the ledger, an event is sent by the peer through a dedicated streaming port. Any applications within the organization can register themselves to listen on that port to get notified. + +The final piece of the puzzle is identities. Every operation in a Hyperledger Fabric network must be digitially signed for the purposes of access control, or provenance/auditing (who did what), or both. As of v1.0, identities are based on the Public Key Infrastructure (PKI)) standards. Every orderer node, peer node and every user/transactor must have a key pair with the public key wrapped in a x.509 certificate signed by a Certificate Authority (CA). Since x.509 is an open standard, Hyperledger Fabric would work with any existing certificate authorities. But it's typically a painful process with lots of potential red taping to get real certificates, so for development purposes it is a popular practice to use self-signed certificates locally generated. As you will see in the later section, the fabric provides tools to make this less painful. + +Also related to identities, you should make a decision on whether [Fabric-CA](http://hyperledger-fabric.readthedocs.io/en/latest/Setup/ca-setup.html) should be part of your solution. This is a server with REST APIs that supports dynamic identity management with registration, enrollment (getting certificates), revocation and re-enrollment. So it is very useful in providing user identities on the fly. But note that user identities provisioned this way are only of the `MEMBER` role in the fabric, which means it won't be able to perform certain operations reserved for the `ADMIN` role: +* create/update channel +* install/instantiate chaincode +* query installed/instantiated chaincodes + +For these privileged operations, the client must use an ADMIN user to submit the request. This will be discussed in more details in the [User identities]() tutorial. + +If you choose to not use Fabric-CA, everything will still work but the application is responsible for managing the user certificates. This will be discussed in more details in the [User identities]() tutorial. + +## Prerequisites + +You will need the following software: +* [Docker](https://www.docker.com/products/overview) - v1.12 or higher +* [Docker Compose](https://docs.docker.com/compose/overview/) - v1.8 or higher +* [Nodejs](https://nodejs.org/en/download/) v6.2.0 - 6.10.0 ( __Node v7+ is not supported__ ) + +## Prepare crypto materials + +As discussed above, identities are established with x.509 certificates. If you think about it, we will need a whole bunch of certificates because there are many identities involved: +* peers need identities to sign endorsements +* orderers need identities to sign proposed blocks for the committers to validate and append to the ledger +* applications need identities to sign transaction requests +* even the Fabric CA themselves also need identities so their signatures in the certificates can be validated + +Luckily there is a tool for that. Follow [this guide](http://hyperledger-fabric.readthedocs.io/en/latest/getting_started.html#using-the-cryptogen-tool) to use the cryptogen tool to generate all the required keys and certificates in one swoop. Recommend the following configuration: + +| Organization | # of nodes | # of users | +| ------------- |:-------------:|:-----------------:| +| orderer org | 1 orderer | 1 admin | +| peer org1 | 2 peers | 1 admin, 1 member | +| peer org2 | 2 peers | 1 admin, 1 member | + +Note that the cryptogen tool will automatically generate identities for the Fabric CA nodes for each orderer and peer organization, which can be used to start the Fabric-CA servers (if you choose to use it as part of the solution as discussed above). In addition, it also generates one admin user of the `ADMIN` role with the privileges to perform admin-level operations listed above. Finally, it also generates regular users (`MEMBER` role) for submitting transactions. + +This would get us all the crypto materials needed to start things up. + +## Getting things rolling for real - the genesis block + +As discussed above, the orderer should be the first step to bootstrap to launch a network. It will need the initial configurations wrapped inside a `genesis block`. Follow the [instructions here](http://hyperledger-fabric.readthedocs.io/en/latest/getting_started.html#using-the-configtxgen-tool) to use the `congigtxgen` tool to generate that. The output, the genesis block for the orderer, will be used in the next step to launch the orderer node. + +## Start the network (no TLS) + +Now we are ready to put it all together. The easiest way to launch the development environment is to use docker-compose. Follow the [instructions here](http://hyperledger-fabric.readthedocs.io/en/latest/getting_started.html#start-the-network-no-tls) to start the network. To minimize the chance to make mistakes, we will run the network without TLS. + +The above steps give you a development environment. Now before you can ask it to process any transactions, you must first create a channel. Next, we will create a channel in [this tutorial](). + diff --git a/docs/app-developer-env-setup.md b/docs/app-developer-env-setup.md deleted file mode 100755 index 08d379c0f4..0000000000 --- a/docs/app-developer-env-setup.md +++ /dev/null @@ -1,50 +0,0 @@ -# Setting up the Full Hyperledger fabric Developer's Environment - - * See [Setting Up The Development Environment](http://hyperledger-fabric.readthedocs.io/en/latest/dev-setup/devenv/) to set up your development environment. - - * The following commands are all issued from the vagrant environment. The following will open a terminal session: - -``` - cd /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 - -``` - * 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"); -``` - - * To build the API reference documentation: - -``` - cd /opt/gopath/src/github.com/hyperledger/fabric-sdk-node - -``` - - * To build the reference documentation in the [Fabric-starter-kit](http://hyperledger-fabric.readthedocs.io/en/latest/#fabric-starter-kit) - -``` - docker exec -it nodesdk /bin/bash - cd /opt/gopath/src/github.com/hyperledger/fabric-sdk-node - -``` - - * The the API reference documentation will be available in: - ``` - /opt/gopath/src/github.com/hyperledger/fabric-sdk-node/doc - ``` - diff --git a/docs/index.md b/docs/index.md index f8a49bf13d..73f1befd9a 100755 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,3 @@ -# Hyperledger Fabric SDK for Node.js The Hyperledger Fabric SDK for Node.js provides a powerful API to interact with a Hyperledger Fabric v1.0 blockchain. The SDK is designed to be used in the Node.js JavaScript runtime. diff --git a/docs/node-sdk-guide.md b/docs/node-sdk-guide.md deleted file mode 100755 index a7f48deb33..0000000000 --- a/docs/node-sdk-guide.md +++ /dev/null @@ -1,32 +0,0 @@ -# Hyperledger fabric Client (HFC) SDK for Node.js - -The Hyperledger fabric Client (HFC) SDK for Node.js provides a powerful and easy to use API to interact with a Hyperledger fabric blockchain. The HFC is designed to be used in the Node.js JavaScript runtime. - -#### Overview and Deep Dive - -* [Application Developer's Overview](app-overview.md) for a topological overview of applications and a blockchain. - -* [Hyperledger fabric Client (HFC) SDK for Node.js](node-sdk-indepth.md) the Node.js client SDK in more depth - -#### Development Environment Choices - -* *Recommended:* [Fabric-starter-kit](http://hyperledger-fabric.readthedocs.io/en/latest/#fabric-starter-kit) uses pre-built docker images for the Node.js client application interacting with Hyperledger fabric blockchain. This environment may suffice for a majority of Node.js application developers. The environment contains a built-in standalone sample ready to go. - -* [Full Hyperledger fabric development environment](app-developer-env-setup.md) on how to set up an environment for developing chaincode and applications. - - **Note:** Only recommended for development of the Hyperledger fabric Client SDK itself. - - -#### Sample Code - -* [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 a blockchain network. - - - -#### Related information - - * 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](http://hyperledger-fabric.readthedocs.io/en/latest/Setup/Chaincode-setup). diff --git a/docs/node-sdk-indepth.md b/docs/node-sdk-indepth.md deleted file mode 100755 index f99537707b..0000000000 --- a/docs/node-sdk-indepth.md +++ /dev/null @@ -1,169 +0,0 @@ -# Hyperledger fabric Client (HFC) SDK for Node.js - -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 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 -``` - -### Terminology - -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. - -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. - -## HFC Objects - -HFC is written in javascript. The source can be found in the `fabric-sdk-node/lib` directory. The reference documentation is generated automatically from this source code and can be found in`fabric-sdk-node/docs` after building the project. - -The following is a high-level description of the HFC objects (classes and interfaces) to help guide you through the object hierarchy. - -* **Chain** - - This is the main top-level class which is the client's representation of a chain. HFC allows you to interact with multiple chains and to share a single `KeyValStore` and `MemberServices` object with multiple chains if needed. For each chain, you add one or more `Peer` objects which represents the endpoint(s) to which HFC connects to transact on the chain. The second peer is used only if the first peer fails. The third peer is used only if both the first and second peers fail, etc. - -* **KeyValStore** - - This is a very simple interface which HFC uses to store and retrieve all persistent data. This data includes private keys, so it is very important to keep this storage secure. The default implementation is a simple file-based version found in the `FileKeyValStore` class. If running in a clustered web application, you will need to either ensure that a shared file system is used, or you must implement your own `KeyValStore` that can be shared among all cluster members. - -* **MemberServices** - - This is an interface representing Membership Services and is implemented by the `MemberServicesImpl` class. It provides security and identity related features such as privacy, unlinkability, and confidentiality. This implementation issues *ECerts* (enrollment certificates) and *TCerts* (transaction certificates). ECerts are for enrollment identity and TCerts are for transactions. - -* **Member** or **User** - - The Member class most often represents an end User who transacts on the chain, but it may also represent other types of members such as peers. From the Member class, you can *register* and *enroll* members or users. This interacts with the `MemberServices` object. You can also deploy, query, and invoke chaincode directly, which interacts with the `Peer`. The implementation for deploy, query and invoke simply creates a temporary `TransactionContext` object and delegates the work to it. - -* **TransactionContext** - - 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 - -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. - - **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 - -### '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) -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 -``` - -### 'dev' mode -For deploying chaincode in development mode see [Writing, Building, and Running Chaincode in a Development Environment](https://github.com/hyperledger/fabric/blob/master/docs/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', - fcn: "init", - args: ["a", "100", "b", "200"] - }; -``` - -### 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. - -### 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. diff --git a/docs/sample-standalone-app.md b/docs/sample-standalone-app.md deleted file mode 100755 index 10dca7002f..0000000000 --- a/docs/sample-standalone-app.md +++ /dev/null @@ -1,49 +0,0 @@ -# Node.js Standalone Application in Vagrant - -This section describes how to run a sample standalone Node.js application which interacts with a Hyperledger fabric blockchain. - -* 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**. - -* Issue the following commands to build the Node.js Client SDK: - -``` - cd /opt/gopath/src/github.com/hyperledger/fabric - -``` - -* Start the membership services and peer processes. We run the peer in dev mode for simplicity. - -``` - cd /opt/gopath/src/github.com/hyperledger/fabric/build/bin - membersrvc > membersrvc.log 2>&1& - peer node start --peer-chaincodedev > peer.log 2>&1& -``` - -* Build and run chaincode example 2: - -``` - cd /opt/gopath/src/github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02 - go build - CORE_CHAINCODE_ID_NAME=mycc CORE_PEER_ADDRESS=0.0.0.0:7051 ./chaincode_example02 > log 2>&1& -``` - -* 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. - - You may retrieve the [sample application](https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/app.js) file: -``` - cd /tmp - curl -o app.js https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/app.js -``` -* Run **npm** to install Hyperledger Fabric Node.js SDK in the `/tmp` directory -``` - npm install /opt/gopath/src/github.com/hyperledger/fabric-sdk-node -``` - -* To run the application : - -``` - CORE_CHAINCODE_ID_NAME=mycc CORE_PEER_ADDRESS=0.0.0.0:7051 MEMBERSRVC_ADDRESS=0.0.0.0:7054 DEPLOY_MODE=dev node app -``` - -Congratulations! You've successfully run your first Hyperledger fabric application. - diff --git a/docs/sample-web-app.md b/docs/sample-web-app.md deleted file mode 100755 index 911942ce08..0000000000 --- a/docs/sample-web-app.md +++ /dev/null @@ -1,13 +0,0 @@ -# Node.js Web Application - -The following is a web application template. It is NOT a complete program. - -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. - -You may retrieve the [sample application]( https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/web-app.js) file: - -``` - curl -o app.js https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/web-app.js -``` - - diff --git a/docs/tutorials.json b/docs/tutorials.json index b10038e489..b8056ba09e 100644 --- a/docs/tutorials.json +++ b/docs/tutorials.json @@ -1,5 +1,8 @@ { - "app-overview": { - "title": "Application Developer's Overview" + "index": { + "title": "Hyperledger Fabric SDK for Node.js Overview" + }, + "app-dev-env-setup": { + "title": "Setting up the Application Developer's Environment" } } \ No newline at end of file