From 51627d72ebd893a22c9433b9b94476f724a0a080 Mon Sep 17 00:00:00 2001 From: Christopher Ferris Date: Sun, 11 Dec 2016 12:21:05 -0500 Subject: [PATCH] Address fab-1346 to begin v1.0 docs Refactored docs to focus on current devenv preference for native docker over vagrant. Remove no longer relevant info for membership services. remove REST API info, and rename CoreAPI.md to CLI.md. Left placeholders for documentation (coming soon). added gnubsd dependency Change-Id: I31c6b56ef892a85c3b79651550b8c6bbd566cdb3 Signed-off-by: Christopher Ferris --- docs/API/CLI.md | 78 ++++ docs/API/CoreAPI.md | 626 ----------------------------- docs/API/MemberServicesAPI.md | 84 +--- docs/Setup/ca-setup.md | 183 +-------- docs/dev-setup/build.md | 135 +------ docs/dev-setup/devenv.md | 116 ++++-- docs/index.md | 101 +++-- docs/starter/fabric-starter-kit.md | 171 +------- mkdocs.yml | 2 +- 9 files changed, 236 insertions(+), 1260 deletions(-) create mode 100644 docs/API/CLI.md delete mode 100644 docs/API/CoreAPI.md diff --git a/docs/API/CLI.md b/docs/API/CLI.md new file mode 100644 index 00000000000..7ef7c0bf0c0 --- /dev/null +++ b/docs/API/CLI.md @@ -0,0 +1,78 @@ +# Command-line Interface (CLI) + +To view the currently available CLI commands, execute the following: + +``` + cd /opt/gopath/src/github.com/hyperledger/fabric + build/bin/peer +``` + +You will see output similar to the example below (**NOTE:** rootcommand below +is hardcoded in [main.go](https://github.com/hyperledger/fabric/blob/master/main.go). +Currently, the build will create a *peer* executable file). + +``` + Usage: + peer [flags] + peer [command] + + Available Commands: + version Print fabric peer version. + node node specific commands. + network network specific commands. + chaincode chaincode specific commands. + help Help about any command + + Flags: + -h, --help[=false]: help for peer + --logging-level="": Default logging level and overrides, see core.yaml for full syntax + --test.coverprofile="coverage.cov": Done + -v, --version[=false]: Show current version number of fabric peer server + + + Use "peer [command] --help" for more information about a command. + +``` + +The `peer` command supports several subcommands and flags, as shown above. To +facilitate its use in scripted applications, the `peer` command always +produces a non-zero return code in the event of command failure. Upon success, +many of the subcommands produce a result on **stdout** as shown in the table +below: + +Command | **stdout** result in the event of success +--- | --- +`version` | String form of `peer.version` defined in [core.yaml](https://github.com/hyperledger/fabric/blob/master/peer/core.yaml) +`node start` | N/A +`node status` | String form of [StatusCode](https://github.com/hyperledger/fabric/blob/master/protos/server_admin.proto#L36) +`node stop` | String form of [StatusCode](https://github.com/hyperledger/fabric/blob/master/protos/server_admin.proto#L36) +`network login` | N/A +`network list` | The list of network connections to the peer node. +`chaincode deploy` | The chaincode container name (hash) required for subsequent `chaincode invoke` and `chaincode query` commands +`chaincode invoke` | The transaction ID (UUID) +`chaincode query` | By default, the query result is formatted as a printable +string. Command line options support writing this value as raw bytes (-r, --raw), +or formatted as the hexadecimal representation of the raw bytes (-x, --hex). If +the query response is empty then nothing is output. + +## Deploy a Chaincode + +Deploy creates the docker image for the chaincode and subsequently deploys the +package to the validating peer. An example is below. + +``` +peer chaincode deploy -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02 -c '{"Function":"init", "Args": ["a","100", "b", "200"]}' +``` +Or: + +``` +peer chaincode deploy -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02 -c '{"Args": ["init", "a","100", "b", "200"]}' +``` + +The response to the chaincode deploy command will contain the chaincode +identifier (hash) which will be required on subsequent `chaincode invoke` +and `chaincode query` commands in order to uniquely identify the deployed +chaincode. + +**Note:** If your GOPATH environment variable contains more than one element, +the chaincode must be found in the first one or deployment will fail. diff --git a/docs/API/CoreAPI.md b/docs/API/CoreAPI.md deleted file mode 100644 index 4b622437003..00000000000 --- a/docs/API/CoreAPI.md +++ /dev/null @@ -1,626 +0,0 @@ -# APIs - CLI, REST, and Node.js - -## Overview - -This document covers the available APIs for interacting with a peer node. Three interface choices are provided: - -1. [CLI](#cli) -2. [REST API](#rest-api) -3. [Node.js Application](#nodejs-application) - * [Using Swagger JS Plugin](#using-swagger-js-plugin) - * [Marbles Demo Application](#marbles-demo-application) - * [Commercial Paper Demo Application](#commercial-paper-demo-application) - -**Note:** If you are working with APIs with security enabled, please review the [security setup instructions](https://github.com/hyperledger/fabric/blob/master/docs/Setup/Chaincode-setup.md#security-setup-optional) before proceeding. - -## CLI - -To view the currently available CLI commands, execute the following: - - cd /opt/gopath/src/github.com/hyperledger/fabric - build/bin/peer - -You will see output similar to the example below (**NOTE:** rootcommand below is hardcoded in [main.go](https://github.com/hyperledger/fabric/blob/master/main.go). Currently, the build will create a *peer* executable file). - -``` - Usage: - peer [flags] - peer [command] - - Available Commands: - version Print fabric peer version. - node node specific commands. - network network specific commands. - chaincode chaincode specific commands. - help Help about any command - - Flags: - -h, --help[=false]: help for peer - --logging-level="": Default logging level and overrides, see core.yaml for full syntax - --test.coverprofile="coverage.cov": Done - -v, --version[=false]: Show current version number of fabric peer server - - - Use "peer [command] --help" for more information about a command. - -``` - -The `peer` command supports several subcommands and flags, as shown above. To -facilitate its use in scripted applications, the `peer` command always -produces a non-zero return code in the event of command failure. Upon success, -many of the subcommands produce a result on **stdout** as shown in the table -below: - -Command | **stdout** result in the event of success ---- | --- -`version` | String form of `peer.version` defined in [core.yaml](https://github.com/hyperledger/fabric/blob/master/peer/core.yaml) -`node start` | N/A -`node status` | String form of [StatusCode](https://github.com/hyperledger/fabric/blob/master/protos/server_admin.proto#L36) -`node stop` | String form of [StatusCode](https://github.com/hyperledger/fabric/blob/master/protos/server_admin.proto#L36) -`network login` | N/A -`network list` | The list of network connections to the peer node. -`chaincode deploy` | The chaincode container name (hash) required for subsequent `chaincode invoke` and `chaincode query` commands -`chaincode invoke` | The transaction ID (UUID) -`chaincode query` | By default, the query result is formatted as a printable string. Command line options support writing this value as raw bytes (-r, --raw), or formatted as the hexadecimal representation of the raw bytes (-x, --hex). If the query response is empty then nothing is output. - - -### Deploy a Chaincode - -Deploy creates the docker image for the chaincode and subsequently deploys the package to the validating peer. An example is below. - -``` -peer chaincode deploy -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02 -c '{"Function":"init", "Args": ["a","100", "b", "200"]}' -``` -Or: - -``` -peer chaincode deploy -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02 -c '{"Args": ["init", "a","100", "b", "200"]}' -``` - -The response to the chaincode deploy command will contain the chaincode identifier (hash) which will be required on subsequent `chaincode invoke` and `chaincode query` commands in order to identify the deployed chaincode. - -With security enabled, modify the command to include the -u parameter passing the username of a logged in user as follows: - -``` -peer chaincode deploy -u jim -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02 -c '{"Function":"init", "Args": ["a","100", "b", "200"]}' -``` - -Or: - -``` -peer chaincode deploy -u jim -p github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02 -c '{"Args": ["init", "a","100", "b", "200"]}' -``` - -**Note:** If your GOPATH environment variable contains more than one element, the chaincode must be found in the first one or deployment will fail. - -### Verify Results - -To verify that the block containing the latest transaction has been added to the blockchain, use the `/chain` REST endpoint from the command line. Target the IP address of either a validating or a non-validating node. In the example below, 172.17.0.2 is the IP address of a validating or a non-validating node and 7050 is the REST interface port defined in [core.yaml](https://github.com/hyperledger/fabric/blob/master/peer/core.yaml). - -`curl 172.17.0.2:7050/chain` - -An example of the response is below. - -``` -{ - "height":1, - "currentBlockHash":"4Yc4yCO95wcpWHW2NLFlf76OGURBBxYZMf3yUyvrEXs5TMai9qNKfy9Yn/==" -} -``` - -The returned BlockchainInfo message is defined inside [fabric.proto](https://github.com/hyperledger/fabric/blob/master/protos/fabric.proto#L96). - -``` -message BlockchainInfo { - uint64 height = 1; - bytes currentBlockHash = 2; - bytes previousBlockHash = 3; -} -``` - -To verify that a specific block is inside the blockchain, use the `/chain/blocks/{Block}` REST endpoint. Likewise, target the IP address of either a validating or a non-validating node on port 7050. - -`curl 172.17.0.2:7050/chain/blocks/0` - -The returned Block message structure is defined inside [fabric.proto](https://github.com/hyperledger/fabric/blob/master/protos/fabric.proto#L84). - -``` -message Block { - uint32 version = 1; - google.protobuf.Timestamp timestamp = 2; - repeated Transaction transactions = 3; - bytes stateHash = 4; - bytes previousBlockHash = 5; - bytes consensusMetadata = 6; - NonHashData nonHashData = 7; -} -``` - -An example of a returned Block structure is below. - -``` -{ - "transactions":[{ - "type":1, - "chaincodeID": { - "path":"github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02" - }, - "payload":"ClwIARJYCk9naXRod...", - "uuid":"abdcec99-ae5e-415e-a8be-1fca8e38ba71" - }], - "stateHash":"PY5YcQRu2g1vjiAqHHshoAhnq8CFP3MqzMslcEAJbnmXDtD+LopmkrUHrPMOGSF5UD7Kxqhbg1XUjmQAi84paw==" -} -``` - -For additional information on the available CLI commands, please see the [protocol specification](https://github.com/hyperledger/fabric/blob/master/docs/protocol-spec.md) section 6.3 on CLI. - -## REST API - -You can work with the REST API through any tool of your choice. For example, the curl command line utility or a browser based client such as the Firefox Rest Client or Chrome Postman. You can likewise trigger REST requests directly through [Swagger](http://swagger.io/). You can utilize the Swagger service directly or, if you prefer, you can set up Swagger locally by following the instructions [here](#to-set-up-swagger-ui). - -**Note:** The default REST interface port is `7050`. It can be configured in [core.yaml](https://github.com/hyperledger/fabric/blob/master/peer/core.yaml) using the `rest.address` property. If using Vagrant, the REST port mapping is defined in [Vagrantfile](https://github.com/hyperledger/fabric/blob/master/devenv/Vagrantfile). - -**Note on constructing a test blockchain** If you want to test the REST API locally, construct a test blockchain by running the TestServerOpenchain_API_GetBlockCount test implemented inside [api_test.go](https://github.com/hyperledger/fabric/blob/master/core/rest/api_test.go). This test will create a test blockchain with 5 blocks. Subsequently restart the peer process. - -``` - cd /opt/gopath/src/github.com/hyperledger/fabric/core/rest - go test -v -run TestServerOpenchain_API_GetBlockCount -``` - -### REST Endpoints - -To learn about the REST API through Swagger, please take a look at the Swagger document [here](https://github.com/hyperledger/fabric/blob/master/core/rest/rest_api.json). You can upload the service description file to the Swagger service directly or, if you prefer, you can set up Swagger locally by following the instructions [here](#to-set-up-swagger-ui). - -* [Block](#block) - * GET /chain/blocks/{Block} -* [Blockchain](#blockchain) - * GET /chain -* [Chaincode](#chaincode) - * POST /chaincode -* [Network](#network) - * GET /network/peers -* [Registrar](#registrar) - * POST /registrar - * DELETE /registrar/{enrollmentID} - * GET /registrar/{enrollmentID} - * GET /registrar/{enrollmentID}/ecert - * GET /registrar/{enrollmentID}/tcert -* [Transactions](#transactions) - * GET /transactions/{UUID} - -#### Block - -* **GET /chain/blocks/{Block}** - -Use the Block API to retrieve the contents of various blocks from the blockchain. The returned Block message structure is defined inside [fabric.proto](https://github.com/hyperledger/fabric/blob/master/protos/fabric.proto#L84). - -``` -message Block { - uint32 version = 1; - google.protobuf.Timestamp Timestamp = 2; - repeated Transaction transactions = 3; - bytes stateHash = 4; - bytes previousBlockHash = 5; -} -``` - -#### Blockchain - -* **GET /chain** - -Use the Chain API to retrieve the current state of the blockchain. The returned BlockchainInfo message is defined inside [fabric.proto](https://github.com/hyperledger/fabric/blob/master/protos/fabric.proto#L96). - -``` -message BlockchainInfo { - uint64 height = 1; - bytes currentBlockHash = 2; - bytes previousBlockHash = 3; -} -``` - -#### Chaincode - -* **POST /chaincode** - -Use the /chaincode endpoint to deploy, invoke, and query a target chaincode. This service endpoint implements the [JSON RPC 2.0 specification](http://www.jsonrpc.org/specification) with the payload identifying the desired chaincode operation within the `method` field. The supported methods are `deploy`, `invoke`, and `query`. - -The /chaincode endpoint implements the [JSON RPC 2.0 specification](http://www.jsonrpc.org/specification) and as such, must have the required fields of `jsonrpc`, `method`, and in our case `params` supplied within the payload. The client should also add the `id` element within the payload if they wish to receive a response to the request. If the `id` element is missing from the request payload, the request is assumed to be a notification and the server will not produce a response. - -The following sample payloads may be used to deploy, invoke, and query a sample chaincode. To deploy a chaincode, supply the [ChaincodeSpec](https://github.com/hyperledger/fabric/blob/master/protos/chaincode.proto#L60) identifying the chaincode to deploy within the request payload. - -Chaincode Deployment Request without security enabled: - -``` -POST host:port/chaincode - -{ - "jsonrpc": "2.0", - "method": "deploy", - "params": { - "type": 1, - "chaincodeID":{ - "path":"github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02" - }, - "ctorMsg": { - "args":["init", "a", "1000", "b", "2000"] - } - }, - "id": 1 -} -``` - -To deploy a chaincode with security enabled, supply the `secureContext` element containing the registrationID of a registered and logged in user together with the payload from above. - -Chaincode Deployment Request with security enabled (add `secureContext` element): - -``` -POST host:port/chaincode - -{ - "jsonrpc": "2.0", - "method": "deploy", - "params": { - "type": 1, - "chaincodeID":{ - "path":"github.com/hyperledger/fabric/examples/chaincode/go/chaincode_example02" - }, - "ctorMsg": { - "args":["init", "a", "1000", "b", "2000"] - }, - "secureContext": "lukas" - }, - "id": 1 -} -``` - -The response to a chaincode deployment request will contain a `status` element confirming successful completion of the request. The response to a successful deployment request will likewise contain the generated chaincode hash which must be used in subsequent invocation and query requests sent to this chaincode. - -Chaincode Deployment Response: - -``` -{ - "jsonrpc": "2.0", - "result": { - "status": "OK", - "message": "52b0d803fc395b5e34d8d4a7cd69fb6aa00099b8fabed83504ac1c5d61a425aca5b3ad3bf96643ea4fdaac132c417c37b00f88fa800de7ece387d008a76d3586" - }, - "id": 1 -} -``` - -To invoke a chaincode, supply the [ChaincodeSpec](https://github.com/hyperledger/fabric/blob/master/protos/chaincode.proto#L60) identifying the chaincode to invoke within the request payload. Note the chaincode `name` field, which is the hash returned from the deployment request. - -Chaincode Invocation Request without security enabled: - -``` -{ - "jsonrpc": "2.0", - "method": "invoke", - "params": { - "type": 1, - "chaincodeID":{ - "name":"52b0d803fc395b5e34d8d4a7cd69fb6aa00099b8fabed83504ac1c5d61a425aca5b3ad3bf96643ea4fdaac132c417c37b00f88fa800de7ece387d008a76d3586" - }, - "ctorMsg": { - "args":["invoke", "a", "b", "100"] - } - }, - "id": 3 -} -``` - -To invoke a chaincode with security enabled, supply the `secureContext` element containing the registrationID of a registered and logged in user together with the payload from above. - -Chaincode Invocation Request with security enabled (add `secureContext` element): - -``` -{ - "jsonrpc": "2.0", - "method": "invoke", - "params": { - "type": 1, - "chaincodeID":{ - "name":"52b0d803fc395b5e34d8d4a7cd69fb6aa00099b8fabed83504ac1c5d61a425aca5b3ad3bf96643ea4fdaac132c417c37b00f88fa800de7ece387d008a76d3586" - }, - "ctorMsg": { - "args":["invoke", "a", "b", "100"] - }, - "secureContext": "lukas" - }, - "id": 3 -} -``` - -The response to a chaincode invocation request will contain a `status` element confirming successful completion of the request. The response will likewise contain the transaction id number for that specific transaction. The client may use the returned transaction id number to check on the status of the transaction after it has been submitted to the system, as the transaction execution is asynchronous. - -Chaincode Invocation Response: - -``` -{ - "jsonrpc": "2.0", - "result": { - "status": "OK", - "message": "5a4540e5-902b-422d-a6ab-e70ab36a2e6d" - }, - "id": 3 -} -``` - -To query a chaincode, supply the [ChaincodeSpec](https://github.com/hyperledger/fabric/blob/master/protos/chaincode.proto#L60) identifying the chaincode to query within the request payload. Note the chaincode `name` field, which is the hash returned from the deployment request. - -Chaincode Query Request without security enabled: - -``` -{ - "jsonrpc": "2.0", - "method": "query", - "params": { - "type": 1, - "chaincodeID":{ - "name":"52b0d803fc395b5e34d8d4a7cd69fb6aa00099b8fabed83504ac1c5d61a425aca5b3ad3bf96643ea4fdaac132c417c37b00f88fa800de7ece387d008a76d3586" - }, - "ctorMsg": { - "args":["query", "a"] - } - }, - "id": 5 -} -``` - -To query a chaincode with security enabled, supply the `secureContext` element containing the registrationID of a registered and logged in user together with the payload from above. - -Chaincode Query Request with security enabled (add `secureContext` element): - -``` -{ - "jsonrpc": "2.0", - "method": "query", - "params": { - "type": 1, - "chaincodeID":{ - "name":"52b0d803fc395b5e34d8d4a7cd69fb6aa00099b8fabed83504ac1c5d61a425aca5b3ad3bf96643ea4fdaac132c417c37b00f88fa800de7ece387d008a76d3586" - }, - "ctorMsg": { - "args":["query", "a"] - }, - "secureContext": "lukas" - }, - "id": 5 -} -``` - -The response to a chaincode query request will contain a `status` element confirming successful completion of the request. The response will likewise contain an appropriate `message`, as defined by the chaincode. The `message` received depends on the chaincode implementation and may be a string or number indicating the value of a specific chaincode variable. - -Chaincode Query Response: - -``` -{ - "jsonrpc": "2.0", - "result": { - "status": "OK", - "message": "-400" - }, - "id": 5 -} -``` - -#### Network - -* **GET /network/peers** - -Use the Network APIs to retrieve information about the network of peer nodes comprising the blockchain network. - -The /network/peers endpoint returns a list of all existing network connections for the target peer node. The list includes both validating and non-validating peers. The list of peers is returned as type [`PeersMessage`](https://github.com/hyperledger/fabric/blob/master/protos/fabric.proto#L138), containing an array of [`PeerEndpoint`](https://github.com/hyperledger/fabric/blob/master/protos/fabric.proto#L127). - -``` -message PeersMessage { - repeated PeerEndpoint peers = 1; -} -``` - -``` -message PeerEndpoint { - PeerID ID = 1; - string address = 2; - enum Type { - UNDEFINED = 0; - VALIDATOR = 1; - NON_VALIDATOR = 2; - } - Type type = 3; - bytes pkiID = 4; -} -``` - -``` -message PeerID { - string name = 1; -} -``` - -#### Registrar - -* **POST /registrar** -* **DELETE /registrar/{enrollmentID}** -* **GET /registrar/{enrollmentID}** -* **GET /registrar/{enrollmentID}/ecert** -* **GET /registrar/{enrollmentID}/tcert** - -Use the Registrar APIs to manage end user registration with the CA. These API endpoints are used to register a user with the CA, determine whether a given user is registered, and to remove any login tokens for a target user preventing them from executing any further transactions. The Registrar APIs are also used to retrieve user enrollment and transaction certificates from the system. - -The /registrar endpoint is used to register a user with the CA. The required Secret payload is defined in [devops.proto](https://github.com/hyperledger/fabric/blob/master/protos/devops.proto#L50). - -``` -message Secret { - string enrollId = 1; - string enrollSecret = 2; -} -``` - -The response to the registration request is either a confirmation of successful registration or an error, containing a reason for the failure. An example of a valid Secret message to register user 'lukas' is shown below. - -``` -{ - "enrollId": "lukas", - "enrollSecret": "NPKYL39uKbkj" -} -``` - -The GET /registrar/{enrollmentID} endpoint is used to confirm whether a given user is registered with the CA. If so, a confirmation will be returned. Otherwise, an authorization error will result. - -The DELETE /registrar/{enrollmentID} endpoint is used to delete login tokens for a target user. If the login tokens are deleted successfully, a confirmation will be returned. Otherwise, an authorization error will result. No payload is required for this endpoint. Note, that registration with the CA is a one time process for a given user, utilizing a single-use registrationID and registrationPW. If the user registration is deleted through this API, the user will not be able to register with the CA a second time. - -The GET /registrar/{enrollmentID}/ecert endpoint is used to retrieve the enrollment certificate of a given user from local storage. If the target user has already registered with the CA, the response will include a URL-encoded version of the enrollment certificate. If the target user has not yet registered, an error will be returned. If the client wishes to use the returned enrollment certificate after retrieval, keep in mind that it must be URL-decoded. This can be accomplished with the QueryUnescape method in the "net/url" package. - -The /registrar/{enrollmentID}/tcert endpoint retrieves the transaction certificates for a given user that has registered with the certificate authority. If the user has registered, a confirmation message will be returned containing an array of URL-encoded transaction certificates. Otherwise, an error will result. The desired number of transaction certificates is specified with the optional 'count' query parameter. The default number of returned transaction certificates is 1; and 500 is the maximum number of certificates that can be retrieved with a single request. If the client wishes to use the returned transaction certificates after retrieval, keep in mind that they must be URL-decoded. This can be accomplished with the QueryUnescape method in the "net/url" package. - -#### Transactions - -* **GET /transactions/{UUID}** - -Use the /transactions/{UUID} endpoint to retrieve an individual transaction matching the UUID from the blockchain. The returned transaction message is defined inside [fabric.proto](https://github.com/hyperledger/fabric/blob/master/protos/fabric.proto#L28). - -``` -message Transaction { - enum Type { - UNDEFINED = 0; - CHAINCODE_DEPLOY = 1; - CHAINCODE_INVOKE = 2; - CHAINCODE_QUERY = 3; - CHAINCODE_TERMINATE = 4; - } - Type type = 1; - bytes chaincodeID = 2; - bytes payload = 3; - string uuid = 4; - google.protobuf.Timestamp timestamp = 5; - - ConfidentialityLevel confidentialityLevel = 6; - bytes nonce = 7; - - bytes cert = 8; - bytes signature = 9; -} -``` - -For additional information on the REST endpoints and more detailed examples, please see the [protocol specification](https://github.com/hyperledger/fabric/blob/master/docs/protocol-spec.md) section 6.2 on the REST API. - -### To set up Swagger-UI - -[Swagger](http://swagger.io/) is a convenient package that allows you to describe and document your REST API in a single file. The REST API is described in [rest_api.json](https://github.com/hyperledger/fabric/blob/master/core/rest/rest_api.json). To interact with the peer node directly through the Swagger-UI, you can upload the available Swagger definition to the [Swagger service](http://swagger.io/). Alternatively, you may set up a Swagger installation on your machine by following the instructions below. - -1. You can use Node.js to serve up the rest_api.json locally. To do so, make sure you have Node.js installed on your local machine. If it is not installed, please download the [Node.js](https://nodejs.org/en/download/) package and install it. - -2. Install the Node.js http-server package with the command below: - - `npm install http-server -g` - -3. Start up an http-server on your local machine to serve up the rest_api.json. - - ``` - cd /opt/gopath/src/github.com/hyperledger/fabric/core/rest - http-server -a 0.0.0.0 -p 5554 --cors - ``` - -4. Make sure that you are successfully able to access the API description document within your browser at this link: - - `http://localhost:5554/rest_api.json` - -5. Download the Swagger-UI package with the following command: - - `git clone https://github.com/swagger-api/swagger-ui.git` - -6. Navigate to the /swagger-ui/dist directory and click on the index.html file to bring up the Swagger-UI interface inside your browser. - -7. Start up the peer node with no connections to a leader or validator as follows. - - ``` - cd /opt/gopath/src/github.com/hyperledger/fabric - build/bin/peer node start - ``` - -8. If you need to construct a test blockchain on the local peer node, run the the TestServerOpenchain_API_GetBlockCount test implemented inside [api_test.go](https://github.com/hyperledger/fabric/blob/master/core/rest/api_test.go). This test will create a blockchain with 5 blocks. Subsequently restart the peer process. - - ``` - cd /opt/gopath/src/github.com/hyperledger/fabric/core/rest - go test -v -run TestServerOpenchain_API_GetBlockCount - ``` - -9. Go back to the Swagger-UI interface inside your browser and load the API description. You should now be able to issue queries against the pre-built blockchain directly from Swagger. - -## Node.js Application - -You can interface with the peer process from a Node.js application. One way to accomplish that is by relying on the Swagger API description document, [rest_api.json](https://github.com/hyperledger/fabric/blob/master/core/rest/rest_api.json ) and the [swagger-js plugin](https://github.com/swagger-api/swagger-js). Another way to accomplish that relies upon the IBM Blockchain [JS SDK](https://github.com/IBM-Blockchain/ibm-blockchain-js). Use the approach that you find the most convenient. - -### [Using Swagger JS Plugin](https://github.com/hyperledger/fabric/blob/master/docs/API/Samples/Sample_1.js) - -* Demonstrates interfacing with a peer node from a Node.js application. -* Utilizes the Node.js swagger-js plugin: https://github.com/swagger-api/swagger-js - -**To run:** - -1. Build and install the [fabric core](https://github.com/hyperledger/fabric/blob/master/README.md#building-the-fabric-core-). - - ``` - cd /opt/gopath/src/github.com/hyperledger/fabric - make peer - ``` - -2. Run a local peer node only (not a complete network) with: - - `build/bin/peer node start` - -3. Set up a test blockchain data structure (with 5 blocks only) by running a test from within Vagrant as follows. Subsequently restart the peer process. - - ``` - cd /opt/gopath/src/github.com/hyperledger/fabric/core/rest - go test -v -run TestServerOpenchain_API_GetBlockCount - ``` - -4. Start up an http-server on your local machine to serve up the rest_api.json. - - ``` - npm install http-server -g - cd /opt/gopath/src/github.com/hyperledger/fabric/core/rest - http-server -a 0.0.0.0 -p 5554 --cors - ``` - -5. Download and unzip [Sample_1.zip](https://github.com/hyperledger/fabric/blob/master/docs/API/Samples/Sample_1.zip) - - ``` - unzip Sample_1.zip -d Sample_1 - cd Sample_1 - ``` - -6. Update the api_url variable within [openchain.js](https://github.com/hyperledger/fabric/blob/master/docs/API/Samples/Sample_1.js) to the appropriate URL if it is not already the default - - `var api_url = 'http://localhost:5554/rest_api.json';` - -7. Run the Node.js app - - `node ./openchain.js` - -You will observe several responses on the console and the program will appear to hang for a few moments at the end. This is expected, as is it waiting for the invocation transaction to complete in order to then execute a query. You can take a look at the sample output of the program inside the 'openchain_test' file located in the Sample_1 directory. - -### [Marbles Demo Application](https://github.com/IBM-Blockchain/marbles) - -* Demonstrates an alternative way of interfacing with a peer node from a Node.js app. -* Demonstrates deploying a Blockchain application as a Bluemix service. - -Hold on to your hats everyone, this application is going to demonstrate transferring marbles between two users leveraging IBM Blockchain. We are going to do this in Node.js and a bit of GoLang. The backend of this application will be the GoLang code running in our blockchain network. The chaincode itself will create a marble by storing it to the chaincode state. The chaincode itself is able to store data as a string in a key/value pair setup. Thus we will stringify JSON objects to store more complex structures. - -For more inforation on the IBM Blockchain marbles demo, set-up, and instructions, please visit [this page](https://github.com/IBM-Blockchain/marbles). - -### [Commercial Paper Demo Application](https://github.com/IBM-Blockchain/cp-web) - -* Demonstrates an alternative way of interfacing with a peer node from a Node.js app. -* Demonstrates deploying a Blockchain application as a Bluemix service. - -This application is a demonstration of how a commercial paper trading network might be implemented on IBM Blockchain. The components of the demo are: - -* An interface for creating new users on the network. -* An interface for creating new commercial papers to trade. -* A Trade Center for buying and selling existing trades. -* A special interface just for auditors of the network to examine trades. - -For more inforation on the IBM Blockchain commercial paper demo, set-up, and instructions, please visit [this page](https://github.com/IBM-Blockchain/cp-web). diff --git a/docs/API/MemberServicesAPI.md b/docs/API/MemberServicesAPI.md index 90f4434813d..ab0fdf911aa 100644 --- a/docs/API/MemberServicesAPI.md +++ b/docs/API/MemberServicesAPI.md @@ -1,85 +1,3 @@ # Certificate Authority API -Each of the CA services is split into two [GRPC](http://www.grpc.io) interfaces, namely a public one (indicated by a _P_ suffix) and an administrator one (indicated by an _A_ suffix). - -## Enrollment Certificate Authority - -The administrator interface of the ECA provides the following functions: - - service ECAA { // admin - rpc RegisterUser(RegisterUserReq) returns (Token); - rpc ReadUserSet(ReadUserSetReq) returns (UserSet); - rpc RevokeCertificate(ECertRevokeReq) returns (CAStatus); // not yet implemented - rpc PublishCRL(ECertCRLReq) returns (CAStatus); // not yet implemented - } - -The `RegisterUser` function allows you to register a new user by specifiying their name and roles in the `RegisterUserReq` structure. If the user has not been registered before, the ECA registers the new user and returns a unique one-time password, which can be used by the user to request their enrollment certificate pair via the public interface of the ECA. Otherwise an error is returned. - -The `ReadUserSet` function allows only auditors to retrieve the list of users registered with the blockchain. - -The public interface of the ECA provides the following functions: - - service ECAP { // public - rpc ReadCACertificate(Empty) returns (Cert); - rpc CreateCertificatePair(ECertCreateReq) returns (ECertCreateResp); - rpc ReadCertificatePair(ECertReadReq) returns (CertPair); - rpc ReadCertificateByHash(Hash) returns (Cert); - rpc RevokeCertificatePair(ECertRevokeReq) returns (CAStatus); // not yet implemented - } - -The `ReadCACertificate` function returns the certificate of the ECA itself. - -The `CreateCertificatePair` function allows a user to create and read their enrollment certificate pair. For this, the user has to do two successive invocations of this function. Firstly, both the signature and encryption public keys have to be handed to the ECA together with the one-time password previously returned by the `RegisterUser` function invocation. The request has to be signed by the user's private signature key to demonstrate that the user is in possession of the private signature key. The ECA in return gives the user a challenge encrypted with the user's public encryption key. The user has to decrypt the challenge, thereby demonstrating that they are in possession of the private encryption key, and then re-issue the certificate creation request - this time with the decrypted challenge instead of the one-time password passed in the invocation. If the challenge has been decrypted correctly, the ECA issues and returns the enrollment certificate pair for the user. - -The `ReadCertificatePair` function allows any user of the blockchain to read the certificate pair of any other user of the blockchain. - -The `ReadCertificatePairByHash` function allows any user of the blockchain to read a certificate from the ECA matching a given hash. - -## Transaction Certificate Authority - -The administrator interface of the TCA provides the following functions: - - service TCAA { // admin - rpc RevokeCertificate(TCertRevokeReq) returns (CAStatus); // not yet implemented - rpc RevokeCertificateSet(TCertRevokeSetReq) returns (CAStatus); // not yet implemented - rpc PublishCRL(TCertCRLReq) returns (CAStatus); // not yet implemented - } - -The public interface of the TCA provides the following functions: - - service TCAP { // public - rpc ReadCACertificate(Empty) returns (Cert); - rpc CreateCertificate(TCertCreateReq) returns (TCertCreateResp); - rpc CreateCertificateSet(TCertCreateSetReq) returns (TCertCreateSetResp); - rpc RevokeCertificate(TCertRevokeReq) returns (CAStatus); // not yet implemented - rpc RevokeCertificateSet(TCertRevokeSetReq) returns (CAStatus); // not yet implemented - } - -The `ReadCACertificate` function returns the certificate of the TCA itself. - -The `CreateCertificate` function allows a user to create and retrieve a new transaction certificate. - -The `CreateCertificateSet` function allows a user to create and retrieve a set of transaction certificates in a single call. - -## TLS Certificate Authority - -The administrator interface of the TLSCA provides the following functions: - - service TLSCAA { // admin - rpc RevokeCertificate(TLSCertRevokeReq) returns (CAStatus); not yet implemented - } - -The public interface of the TLSCA provides the following functions: - - service TLSCAP { // public - rpc ReadCACertificate(Empty) returns (Cert); - rpc CreateCertificate(TLSCertCreateReq) returns (TLSCertCreateResp); - rpc ReadCertificate(TLSCertReadReq) returns (Cert); - rpc RevokeCertificate(TLSCertRevokeReq) returns (CAStatus); // not yet implemented - } - -The `ReadCACertificate` function returns the certificate of the TLSCA itself. - -The `CreateCertificate` function allows a user to create and retrieve a new TLS certificate. - -The `ReadCertificate` function allows a user to retrieve a previously created TLS certificate. +**Coming soon** diff --git a/docs/Setup/ca-setup.md b/docs/Setup/ca-setup.md index 2919bce0b2c..326b5f25591 100644 --- a/docs/Setup/ca-setup.md +++ b/docs/Setup/ca-setup.md @@ -1,182 +1,3 @@ -## Certificate Authority (CA) Setup +## Fabric COP Setup -The _Certificate Authority_ (CA) provides a number of certificate services to users of a blockchain. More specifically, these services relate to _user enrollment_, _transactions_ invoked on the blockchain, and _TLS_-secured connections between users or components of the blockchain. - -This guide builds on either the [fabric developer's setup](../dev-setup/devenv.md) or the prerequisites articulated in the [fabric network setup](Network-setup.md) guide. If you have not already set up your environment with one of those guides, please do so before continuing. - -### Enrollment Certificate Authority - -The _enrollment certificate authority_ (ECA) allows new users to register with the blockchain network and enables registered users to request an _enrollment certificate pair_. One certificate is for data signing, one is for data encryption. The public keys to be embedded in the certificates have to be of type ECDSA, whereby the key for data encryption is then converted by the user to be used in an [ECIES](https://en.wikipedia.org/wiki/Integrated_Encryption_Scheme) (Elliptic Curve Integrated Encryption System) fashion. - -### Transaction Certificate Authority - -Once a user is enrolled, he or she can also request _transaction certificates_ from the _transaction certificate authority_ (TCA). These certificates are to be used for deploying Chaincode and for invoking Chaincode transactions on the blockchain. Although a single _transaction certificate_ can be used for multiple transactions, for privacy reasons it is recommended that a new _transaction certificate_ be used for each transaction. - -### TLS Certificate Authority - -In addition to _enrollment certificates_ and _transaction certificates_, users will need _TLS certificates_ to secure their communication channels. _TLS certificates_ can be requested from the _TLS certificate authority_ (TLSCA). - -## Configuration - -All CA services are provided by a single process, which can be configured by setting parameters in the CA configuration file `membersrvc.yaml`, which is located in the same directory as the CA binary. More specifically, the following parameters can be set: - -- `server.gomaxprocs`: limits the number of operating system threads used by the CA. -- `server.rootpath`: the root path of the directory where the CA stores its state. -- `server.cadir`: the name of the directory where the CA stores its state. -- `server.port`: the port at which all CA services listen (multiplexing of services over the same port is provided by [GRPC](http://www.grpc.io)). - -Furthermore, logging levels can be enabled/disabled by adjusting the following settings: - -- `logging.trace` (off by default, useful for debugging the code only) -- `logging.info` -- `logging.warning` -- `logging.error` -- `logging.panic` - -Alternatively, these fields can be set via environment variables, which---if set---have precedence over entries in the yaml file. The corresponding environment variables are named as follows: - -``` - MEMBERSRVC_CA_SERVER_GOMAXPROCS - MEMBERSRVC_CA_SERVER_ROOTPATH - MEMBERSRVC_CA_SERVER_CADIR - MEMBERSRVC_CA_SERVER_PORT -``` - -In addition, the CA may be preloaded with registered users, where each user's name, roles, and password are specified: - -``` - eca: - users: - alice: 2 DRJ20pEql15a - bob: 4 7avZQLwcUe9q -``` -The role value is simply a bitmask of the following: -``` - CLIENT = 1; - PEER = 2; - VALIDATOR = 4; - AUDITOR = 8; -``` - -For example, a peer that is also a validator would have a role value of 6. - -When the CA is started for the first time, it will generate all of its required state (e.g., internal databases, CA certificates, blockchain keys, etc.) and writes this state to the directory given in its configuration. The certificates for the CA services (i.e., for the ECA, TCA, and TLSCA) are self-signed as the current default. If those certificates shall be signed by some root CA, this can be done manually by using the `*.priv` and `*.pub` private and public keys in the CA state directory, and replacing the self-signed `*.cert` certificates with root-signed ones. The next time the CA is launched, it will read and use those root-signed certificates. - -## Operating the CA - -You can either [build and run](#build-and-run) the CA from source. Or, you can use Docker Compose and work with the published images on DockerHub, or some other Docker registry. Using Docker Compose is by far the simplest approach. - -### Docker Compose - -Here's a sample docker-compose.yml for the CA. - -``` -membersrvc: - image: hyperledger/fabric-membersrvc - command: membersrvc -``` - -The corresponding docker-compose.yml for running Docker on Mac or Windows natively looks like this: - -``` -membersrvc: - image: hyperledger/fabric-membersrvc - ports: - - "7054:7054" - command: membersrvc -``` - -If you are launching one or more `peer` nodes in the same docker-compose.yml, then you will want to add a delay to the start of the peer to allow sufficient time for the CA to start, before the peer attempts to connect to it. - -``` -membersrvc: - image: hyperledger/fabric-membersrvc - command: membersrvc -vp0: - image: hyperledger/fabric-peer - environment: - - CORE_PEER_ADDRESSAUTODETECT=true - - CORE_VM_ENDPOINT=http://172.17.0.1:2375 - - CORE_LOGGING_LEVEL=DEBUG - - CORE_PEER_ID=vp0 - - CORE_SECURITY_ENROLLID=test_vp0 - - CORE_SECURITY_ENROLLSECRET=MwYpmSRjupbT - links: - - membersrvc - command: sh -c "sleep 5; peer node start" -``` - -The corresponding docker-compose.yml for running Docker on Mac or Windows natively looks like this: - -``` -membersrvc: - image: hyperledger/fabric-membersrvc - ports: - - "7054:7054" - command: membersrvc -vp0: - image: hyperledger/fabric-peer - ports: - - "7050:7050" - - "7051:7051" - - "7052:7052" - environment: - - CORE_PEER_ADDRESSAUTODETECT=true - - CORE_VM_ENDPOINT=unix:///var/run/docker.sock - - CORE_LOGGING_LEVEL=DEBUG - - CORE_PEER_ID=vp0 - - CORE_SECURITY_ENROLLID=test_vp0 - - CORE_SECURITY_ENROLLSECRET=MwYpmSRjupbT - links: - - membersrvc - command: sh -c "sleep 5; peer node start" -``` - -### Build and Run - -The CA can be built with the following command executed in the `membersrvc` directory: - -``` -cd $GOPATH/src/github.com/hyperledger/fabric -make membersrvc -``` - -The CA can be started with the following command: - -``` -build/bin/membersrvc -``` - -**Note:** the CA must be started before any of the fabric peer nodes, to allow the CA to have initialized before any peer nodes attempt to connect to it. - -The CA looks for an `membersrvc.yaml` configuration file in $GOPATH/src/github.com/hyperledger/fabric/membersrvc. If the CA is started for the first time, it creates all its required state (e.g., internal databases, CA certificates, blockchain keys, etc.) and writes that state to the directory given in the CA configuration. - - +**Coming soon** diff --git a/docs/dev-setup/build.md b/docs/dev-setup/build.md index 4ba48393940..8e59888248e 100644 --- a/docs/dev-setup/build.md +++ b/docs/dev-setup/build.md @@ -2,64 +2,13 @@ The following instructions assume that you have already set up your [development environment](devenv.md). -To access your VM, run `vagrant ssh` from within the devenv directory of your locally cloned fabric repository. - -``` -cd $GOPATH/src/github.com/hyperledger/fabric/devenv -vagrant ssh -``` - -From within the VM, you can build, run, and test your environment. +To build the Fabric: ``` cd $GOPATH/src/github.com/hyperledger/fabric -make peer -``` - -To see what commands are available, simply execute the following commands: -``` -peer help -``` - -You should see the following output: - -``` - Usage: - peer [command] - - Available Commands: - node node specific commands. - network network specific commands. - chaincode chaincode specific commands. - help Help about any command - - Flags: - -h, --help[=false]: help for peer - --logging-level="": Default logging level and overrides, see core.yaml for full syntax - - - Use "peer [command] --help" for more information about a command. -``` - -The `peer node start` command will initiate a peer process, with which one can interact by executing other commands. For example, the `peer node status` command will return the status of the running peer. The full list of commands is the following: - -``` - node - start Starts the node. - status Returns status of the node. - stop Stops the running node. - network - login Logs in user to CLI. - list Lists all network peers. - chaincode - deploy Deploy the specified chaincode to the network. - invoke Invoke the specified chaincode. - query Query using the specified chaincode. - help Help about any command +make dist-clean all ``` -**Note:** If your GOPATH environment variable contains more than one element, the chaincode must be found in the first one or deployment will fail. - ### Running the unit tests Use the following sequence to run all unit tests @@ -80,64 +29,28 @@ go test -v -run=TestGetFoo You must also run the Node.js unit tests to insure that the Node.js client SDK is not broken by your changes. To run the Node.js unit tests, follow the instructions [here](https://github.com/hyperledger/fabric-sdk-node/README.md). ### Running Behave BDD Tests + +**Note:** currently, the behave tests must be run from within in the Vagrant +environment. See the devenv setup instructions if you have not already set up +your [Vagrant environment](devenv.md#Boostrapping-the-VM-using-Vagrant). + [Behave](http://pythonhosted.org/behave/) tests will setup networks of peers with different security and consensus configurations and verify that transactions run properly. To run these tests ``` cd $GOPATH/src/github.com/hyperledger/fabric make behave ``` -Some of the Behave tests run inside Docker containers. If a test fails and you want to have the logs from the Docker containers, run the tests with this option -``` -behave -D logs=Y -``` - -Note, in order to run behave directly, you must run 'make images' first to build the necessary `peer` and `member services` docker images. These images can also be individually built when `go test` is called with the following parameters: +Some of the Behave tests run inside Docker containers. If a test fails and you want to have the logs from the Docker containers, run the tests with this option: ``` -go test github.com/hyperledger/fabric/core/container -run=BuildImage_Peer -go test github.com/hyperledger/fabric/core/container -run=BuildImage_Obcca +cd $GOPATH/src/github.com/hyperledger/fabric/bddtests +behave -D logs=Y ``` ## Building outside of Vagrant -It is possible to build the project and run peers outside of Vagrant. Generally speaking, one has to 'translate' the vagrant [setup file](https://github.com/hyperledger/fabric/blob/master/devenv/setup.sh) to the platform of your choice. - -### Prerequisites -* [Git client](https://git-scm.com/downloads) -* [Go](https://golang.org/) - 1.6 or later -* [RocksDB](https://github.com/facebook/rocksdb/blob/master/INSTALL.md) version 4.1 and its dependencies -* [Docker](https://docs.docker.com/engine/installation/) -* [Pip](https://pip.pypa.io/en/stable/installing/) -* Set the maximum number of open files to 10000 or greater for your OS - -### Docker -Make sure that the Docker daemon initialization includes the options -``` --H tcp://0.0.0.0:2375 -H unix:///var/run/docker.sock -``` - -Typically, docker runs as a `service` task, with configuration file at `/etc/default/docker`. - -Be aware that the Docker bridge (the `CORE_VM_ENDPOINT`) may not come -up at the IP address currently assumed by the test environment -(`172.17.0.1`). Use `ifconfig` or `ip addr` to find the docker bridge. - -### Building RocksDB -``` -apt-get install -y libsnappy-dev zlib1g-dev libbz2-dev -cd /tmp -git clone https://github.com/facebook/rocksdb.git -cd rocksdb -git checkout v4.1 -PORTABLE=1 make shared_lib -INSTALL_PATH=/usr/local make install-shared -``` - -### `pip`, `behave` and `docker-compose` -``` -pip install --upgrade pip -pip install behave nose docker-compose -pip install -I flask==0.10.1 python-dateutil==2.2 pytz==2014.3 pyyaml==3.10 couchdb==1.0 flask-cors==2.0.1 requests==2.4.3 -``` +It is possible to build the project and run peers outside of Vagrant. Generally +speaking, one has to 'translate' the vagrant [setup file](https://github.com/hyperledger/fabric/blob/master/devenv/setup.sh) +to the platform of your choice. ### Building on Z To make building on Z easier and faster, [this script](https://github.com/hyperledger/fabric/tree/master/devenv/setupRHELonZ.sh) is provided (which is similar to the [setup file](https://github.com/hyperledger/fabric/blob/master/devenv/setup.sh) provided for vagrant). This script has been tested only on RHEL 7.2 and has some assumptions one might want to re-visit (firewall settings, development as root user, etc.). It is however sufficient for development in a personally-assigned VM instance. @@ -173,28 +86,6 @@ cd $GOPATH/src/github.com/hyperledger/fabric make dist-clean all ``` -### Building natively on OSX -First, install Docker, as described [here](https://docs.docker.com/engine/installation/mac/). -The database by default writes to /var/hyperledger. You can override this in the `core.yaml` configuration file, under `peer.fileSystemPath`. - -``` -brew install go rocksdb snappy gnu-tar -# For RocksDB version 4.1, you need to compile your own locally -cd /tmp -git clone https://github.com/facebook/rocksdb.git -cd rocksdb -git checkout v4.1 -PORTABLE=1 make shared_lib -INSTALL_PATH=/usr/local make install-shared - -# You will need the following two lines for every shell you want to use -eval $(docker-machine env) -export PATH="/usr/local/opt/gnu-tar/libexec/gnubin:$PATH" - -cd $GOPATH/src/github.com/hyperledger/fabric -make all -``` - ## Configuration Configuration utilizes the [viper](https://github.com/spf13/viper) and [cobra](https://github.com/spf13/cobra) libraries. diff --git a/docs/dev-setup/devenv.md b/docs/dev-setup/devenv.md index c12a70b943e..215659ddd68 100644 --- a/docs/dev-setup/devenv.md +++ b/docs/dev-setup/devenv.md @@ -1,31 +1,64 @@ ## Setting up the development environment ### Overview -The current development environment utilizes Vagrant running an Ubuntu image, which in turn launches Docker containers. Conceptually, the Host launches a VM, which in turn launches Docker containers. -**Host -> VM -> Docker** - -This model allows developers to leverage their favorite OS/editors and execute the system in a controlled environment that is consistent amongst the development team. - -- Note that your Host should not run within a VM. If you attempt this, the VM within your Host may fail to boot with a message indicating that VT-x is not available. +Through the v0.6 release, the development environment utilized Vagrant running +an Ubuntu image, which in turn launched Docker containers as a means of +ensuring a consistent experience for developers who might be working with +varying platforms, such as MacOSX, Windows, Linux, or whatever. Advances in +Docker have enabled native support on the most popular development platforms: +MacOSX and Windows. Hence, we have reworked our build to take full advantage +of these advances. While we still maintain a Vagrant based approach that can +be used for older versions of MacOSX and Windows that Docker does not support, +we strongly encourage that the non-Vagrant development setup be used. + +Note that while the Vagrant-based development setup could not be used in a +cloud context, the Docker-based build does support cloud platforms such as AWS, +Azure, Google and IBM to name a few. Please follow the instructions for Ubuntu +builds, below. ### Prerequisites * [Git client](https://git-scm.com/downloads) * [Go](https://golang.org/) - 1.6 or later -* [Vagrant](https://www.vagrantup.com/) - 1.7.4 or later -* [VirtualBox](https://www.virtualbox.org/) - 5.0 or later +* For MacOSX, [Xcode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12) +must be installed +* [Docker](https://www.docker.com/products/overview) - 1.12 or later +* [Pip](https://pip.pypa.io/en/stable/installing/) +* (MacOSX) you may need to install gnutar, as MacOSX comes with bsdtar as the +default, but the build uses some gnutar flags. You can use Homebrew to install +it as follows: + +``` +brew install gnu-tar --with-default-names +``` + +* (only if using Vagrant) - [Vagrant](https://www.vagrantup.com/) - 1.7.4 or +later +* (only if using Vagrant) - [VirtualBox](https://www.virtualbox.org/) - 5.0 or +later * BIOS Enabled Virtualization - Varies based on hardware -- Note: The BIOS Enabled Virtualization may be within the CPU or Security settings of the BIOS +- Note: The BIOS Enabled Virtualization may be within the CPU or Security +settings of the BIOS + +### `pip`, `behave` and `docker-compose` + +``` +pip install --upgrade pip +pip install behave nose docker-compose +pip install -I flask==0.10.1 python-dateutil==2.2 pytz==2014.3 pyyaml==3.10 couchdb==1.0 flask-cors==2.0.1 requests==2.4.3 +``` ### Steps #### Set your GOPATH -Make sure you have properly setup your Host's [GOPATH environment variable](https://github.com/golang/go/wiki/GOPATH). This allows for both building within the Host and the VM. +Make sure you have properly setup your Host's [GOPATH environment variable](https://github.com/golang/go/wiki/GOPATH). This allows for both +building within the Host and the VM. #### Note to Windows users -If you are running Windows, before running any `git clone` commands, run the following command. +If you are running Windows, before running any `git clone` commands, run the +following command. ``` git config --get core.autocrlf ``` @@ -33,11 +66,17 @@ If `core.autocrlf` is set to `true`, you must set it to `false` by running ``` git config --global core.autocrlf false ``` -If you continue with `core.autocrlf` set to `true`, the `vagrant up` command will fail with the error `./setup.sh: /bin/bash^M: bad interpreter: No such file or directory` +If you continue with `core.autocrlf` set to `true`, the `vagrant up` command +will fail with the error: + +`./setup.sh: /bin/bash^M: bad interpreter: No such file or directory` #### Cloning the Fabric project -Since the Fabric project is a `Go` project, you'll need to clone the Fabric repo to your $GOPATH/src directory. If your $GOPATH has multiple path components, then you will want to use the first one. There's a little bit of setup needed: +Since the Fabric project is a `Go` project, you'll need to clone the Fabric +repo to your $GOPATH/src directory. If your $GOPATH has multiple path +components, then you will want to use the first one. There's a little bit of +setup needed: ``` cd $GOPATH/src @@ -45,36 +84,63 @@ mkdir -p github.com/hyperledger cd github.com/hyperledger ``` -Recall that we are using `Gerrit` for source control, which has its own internal git repositories. Hence, we will need to [clone from Gerrit](../Gerrit/gerrit.md#Working-with-a-local-clone-of-the-repository). For brevity, the command is as follows: +Recall that we are using `Gerrit` for source control, which has its own internal +git repositories. Hence, we will need to clone from [Gerrit](../Gerrit/gerrit.md#Working-with-a-local-clone-of-the-repository). For +brevity, the command is as follows: ``` git clone ssh://LFID@gerrit.hyperledger.org:29418/fabric && scp -p -P 29418 LFID@gerrit.hyperledger.org:hooks/commit-msg fabric/.git/hooks/ ``` -**Note:** of course, you would want to replace `LFID` with your [Linux Foundation ID](../Gerrit/lf-account.md). +**Note:** Of course, you would want to replace `LFID` with your own +[Linux Foundation ID](../Gerrit/lf-account.md). #### Boostrapping the VM using Vagrant -Now you're ready to launch Vagrant. +If you are planning on using the Vagrant developer environment, the following +steps apply. **Again, we recommend against its use except for developers that +are limited to older versions of MacOSX and Windows that are not supported by +Docker for Mac or Windows.** ``` cd $GOPATH/src/github.com/hyperledger/fabric/devenv vagrant up ``` -Go get coffee... this will take a few minutes. Once complete, you should be able to `ssh` into the Vagrant VM just created. +Go get coffee... this will take a few minutes. Once complete, you should be able +to `ssh` into the Vagrant VM just created. + ``` vagrant ssh ``` +Once inside the VM, you can find the peer project under +`$GOPATH/src/github.com/hyperledger/fabric`. It is also mounted as +`/hyperledger`. + ### Building the fabric -Once you have your vagrant development environment established, you can proceed to [build and test](build.md) the fabric. Once inside the VM, you can find the peer project under `$GOPATH/src/github.com/hyperledger/fabric`. It is also mounted as `/hyperledger`. +Once you have all the dependencies installed, and have cloned the repository, +you can proceed to [build and test](build.md) the fabric. ### Notes -**NOTE:** any time you change any of the files in your local fabric directory (under `$GOPATH/src/github.com/hyperledger/fabric`), the update will be instantly available within the VM fabric directory. - -**NOTE:** If you intend to run the development environment behind an HTTP Proxy, you need to configure the guest so that the provisioning process may complete. You can achieve this via the *vagrant-proxyconf* plugin. Install with `vagrant plugin install vagrant-proxyconf` and then set the VAGRANT_HTTP_PROXY and VAGRANT_HTTPS_PROXY environment variables *before* you execute `vagrant up`. More details are available here: https://github.com/tmatilai/vagrant-proxyconf/ - -**NOTE:** The first time you run this command it may take quite a while to complete (it could take 30 minutes or more depending on your environment) and at times it may look like it's not doing anything. As long you don't get any error messages just leave it alone, it's all good, it's just cranking. - -**NOTE to Windows 10 Users:** There is a known problem with vagrant on Windows 10 (see [mitchellh/vagrant#6754](https://github.com/mitchellh/vagrant/issues/6754)). If the `vagrant up` command fails it may be because you do not have Microsoft Visual C++ Redistributable installed. You can download the missing package at the following address: http://www.microsoft.com/en-us/download/details.aspx?id=8328 +**NOTE:** Any time you change any of the files in your local fabric directory +(under `$GOPATH/src/github.com/hyperledger/fabric`), the update will be +instantly available within the VM fabric directory. + +**NOTE:** If you intend to run the development environment behind an HTTP Proxy, +you need to configure the guest so that the provisioning process may complete. +You can achieve this via the *vagrant-proxyconf* plugin. Install with +`vagrant plugin install vagrant-proxyconf` and then set the VAGRANT_HTTP_PROXY +and VAGRANT_HTTPS_PROXY environment variables *before* you execute `vagrant up`. +More details are available here: https://github.com/tmatilai/vagrant-proxyconf/ + +**NOTE:** The first time you run this command it may take quite a while to +complete (it could take 30 minutes or more depending on your environment) and +at times it may look like it's not doing anything. As long you don't get any +error messages just leave it alone, it's all good, it's just cranking. + +**NOTE to Windows 10 Users:** There is a known problem with vagrant on Windows +10 (see [mitchellh/vagrant#6754](https://github.com/mitchellh/vagrant/issues/6754)). +If the `vagrant up` command fails it may be because you do not have the Microsoft +Visual C++ Redistributable package installed. You can download the missing package at +the following address: http://www.microsoft.com/en-us/download/details.aspx?id=8328 diff --git a/docs/index.md b/docs/index.md index 139c1a260c4..03b1d79a613 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,26 +12,26 @@ document](https://goo.gl/4edNRc). # Hyperledger Fabric -The fabric is an implementation of blockchain technology, leveraging familiar +The Fabric is an implementation of blockchain technology, leveraging familiar and proven technologies. It is a modular architecture allowing pluggable implementations of various function. It features powerful container technology to host any mainstream language for smart contracts development. ## Releases -The fabric releases are documented [here](releases.md). We have just +The Fabric releases are documented [here](releases.md). We released our second release under the governance of the Hyperledger Project - -v0.6-preview. +v0.6-preview in October, 2016. -## Fabric Starter Kit +If you are seeking a stable version of the Hyperledger Fabric on which to +develop applications or explore the technology, we **strongly recommend** that +you use the v0.6 [Starter Kit](http://hyperledger-fabric.readthedocs.io/en/v0.6/starter/fabric-starter-kit/) +while the v1.0 architectural refactoring is in development. -If you'd like to dive right in and get an operational experience on your local -server or laptop to begin development, we have just the thing for you. We have -created a standalone Docker-based [starter kit](starter/fabric-starter-kit.md) -that leverages the latest published Docker images that you can run on your -laptop and be up and running in no time. That should get you going with a -sample application and some simple chaincode. From there, you can go deeper -by exploring our [developer guides](#developer-guides). +If you'd like a taste of what the Fabric v1.0 architecture has in store, we +invite you to read the preview [here](abstract_v1.md). Finally, if you are +adventurous, we invite you to explore the current state of development with +the caveat that it is not yet completely stable. ## Contributing to the project @@ -41,7 +41,7 @@ documented in the [Fabric developer's guide](#fabric-developer-guide) below. ## Maintainers -The project's [maintainers](MAINTAINERS.md): are responsible for reviewing and +The project's [maintainers](MAINTAINERS.md) are responsible for reviewing and merging all patches submitted for review and they guide the over-all technical direction of the project within the guidelines established by the Hyperledger Project's Technical Steering Committee (TSC). @@ -55,10 +55,10 @@ and we take longer running discussions/decisions to the [mailing list](http://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric). ## Still Have Questions? -We try to maintain a comprehensive set of documentation (see below) for various audiences. -However, we realize that often there are questions that remain unanswered. For -any technical questions relating to the Hyperledger Fabric project not answered -in this documentation, please use +We try to maintain a comprehensive set of documentation (see below) for various +audiences. However, we realize that often there are questions that remain +unanswered. For any technical questions relating to the Hyperledger Fabric +project not answered in this documentation, please use [StackOverflow](http://stackoverflow.com/questions/tagged/hyperledger). If you need help finding things, please don't hesitate to send a note to the [mailing list](http://lists.hyperledger.org/mailman/listinfo/hyperledger-fabric), @@ -66,7 +66,7 @@ or ask on [Slack]((https://slack.hyperledger.org/)). # Hyperledger Fabric Documentation -The Hyperledger fabric is an implementation of blockchain technology, that has +The Hyperledger Fabric is an implementation of blockchain technology, that has been collaboratively developed under the Linux Foundation's [Hyperledger Project](http://hyperledger.org). It leverages familiar and proven technologies, and offers a modular architecture @@ -81,22 +81,17 @@ Below, you'll find the following sections: * [Read All About It](#read-all-about-it) * [Developer guides](#developer-guides) - * [Chaincode developer's guide](#chaincode-developer-guide) * [Application developer's guide](#application-developer-guide) * [Fabric developer's guide](#fabric-developer-guide) * [Operations guide](#operations-guide) ## Read all about it -If you are new to the project, you can begin by reviewing the following links. -If you'd prefer to dive right in, see the -[Quickstart](#quickstart-documentation) section, below. +If you are new to the project, you might want to familiarize yourself with some +of the basics before diving into either developing applications using the +Hyperledger Fabric, or collaborating with us on our journey to continuously +extend and improve its capabilities. -- [Whitepaper WG](https://github.com/hyperledger/hyperledger/wiki/Whitepaper-WG): -where the community is developing a whitepaper to explain the motivation and -goals for the project. -- [Requirements WG](https://github.com/hyperledger/hyperledger/wiki/Requirements-WG): -where the community is developing use cases and requirements. - [Canonical use cases](biz/usecases.md) - [Glossary](glossary.md): to understand the terminology that we use throughout the Fabric project's documentation. @@ -104,27 +99,27 @@ the Fabric project's documentation. # Developer guides -## Chaincode developer guide - -- [Setting up the development environment](dev-setup/devenv.md): when developing -and testing Chaincode, or an application that leverages the fabric API or SDK, -you'll probably want to run the fabric locally on your laptop to test. You can -use the same setup that Fabric developers use. -- [Setting Up a Network For Development](Setup/Network-setup.md): alternately, you -can follow these instructions for setting up a local network for Chaincode -development without the entire fabric development environment setup. -- [Writing, Building, and Running Chaincode in a Development -Environment](Setup/Chaincode-setup.md): a step-by-step guide to writing and -testing Chaincode. -- [Chaincode FAQ](FAQ/chaincode_FAQ.md): a FAQ for all of your burning questions -relating to Chaincode. +There are two distinct types of developers for which we have authored this +documentation: 1) [application developers](#application-developer-guide) +building applications and solutions using the Hyperledger Fabric 2) developers +who want to engage in the [development of the Hyperledger Fabric](#fabric-developer-guide) +itself. We distinguish these two personas because the development setup +for the Hyperledger Fabric developer is much more involved as they need to +be able to build the software and there are additional prerequisites that need +to be installed that are largely unnecessary for developers building +applications. ## Application developer guide -- [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 (*deprecated*). -- [Node.js SDK](http://fabric-sdk-node.readthedocs.io/en/latest/node-sdk-guide): working with the Node.js SDK. +- [CLI](API/CLI.md): working with the command-line interface. +- [Node.js SDK](http://fabric-sdk-node.readthedocs.io/en/latest/node-sdk-guide): +working with the Node.js SDK. +- Java SDK (coming soon). +- Python SDK (coming soon). +- [Writing, Building, and Running Chaincode](Setup/Chaincode-setup.md): +a step-by-step guide to developing and testing Chaincode. +- [Chaincode FAQ](FAQ/chaincode_FAQ.md): a FAQ for all of your burning questions +relating to Chaincode. ## Fabric developer guide @@ -132,26 +127,24 @@ relating to Chaincode. yourself with the project's contribution guidelines. - [Setting up the development environment](dev-setup/devenv.md): after that, you will want to set up your development environment. -- [Building the fabric core](dev-setup/build.md): next, try building the project +- [Building the Fabric core](dev-setup/build.md): next, try building the project in your local development environment to ensure that everything is set up correctly. - [Building outside of Vagrant](dev-setup/build.md#building-outside-of-vagrant): - for the *adventurous*, you might try to build outside of the standard Vagrant - development environment. + for the *adventurous*, you might try to build outside of the standard + Vagrant development environment. - [Logging control](Setup/logging-control.md): describes how to tweak the logging - levels of various components within the fabric. + levels of various components within the Fabric. - [License header](dev-setup/headers.txt): every source file must include this license header modified to include a copyright statement for the principle author(s). # Operations guide -- [Setting Up a Network](Setup/Network-setup.md): instructions for setting up a - network of fabric peers. -- [Certificate Authority (CA) Setup](Setup/ca-setup.md): setting up a CA to - support identity, security (authentication/authorization), privacy and - confidentiality. -- [Application ACL](tech/application-ACL.md): working with access control lists. +(coming soon) + +**Note:** if you are looking for instructions to operate the fabric for a POC, +we recommend that you use the more stable v0.6 [Starter Kit](http://hyperledger-fabric.readthedocs.io/en/v0.6/starter/fabric-starter-kit/) # License The Hyperledger Project uses the [Apache License Version 2.0](LICENSE) software diff --git a/docs/starter/fabric-starter-kit.md b/docs/starter/fabric-starter-kit.md index 96c8e35d37a..573eedd8769 100755 --- a/docs/starter/fabric-starter-kit.md +++ b/docs/starter/fabric-starter-kit.md @@ -1,171 +1,6 @@ # Fabric Starter Kit -This section describes how to set up a self-contained environment for -application development with the Hyperledger fabric. The setup -uses **Docker** to provide a controlled environment with all the necessary -Hyperledger fabric components to support a Node.js application built with -the fabric's Node.js SDK, and chaincode written in Go. +**Coming soon for v1.0** -There are three Docker images that, when run, will provide a basic -network environment. There is an image to run a single `peer`, one to run -the `membersrvc`, and one to run both your Node.js application and your -chaincode. See [Application Developer's Overview](http://fabric-sdk-node.readthedocs.io/en/latest/app-overview) on how the -components running within the containers will communicate. - -The starter kit comes with a sample Node.js application ready to execute and -sample chaincode. The starter kit will be running in chaincode developer mode. -In this mode, the chaincode is built and started prior to the application -making a call to deploy it. - -**Note:** The deployment of chaincode in network mode requires that the -Hyperledger fabric Node.js SDK has access to the chaincode source code and all -of its dependencies, in order to properly build a deploy request. It also -requires that the `peer` have access to the Docker daemon to be able to build -and deploy the new Docker image that will run the chaincode. *This is a more -complicated configuration and not suitable to an introduction to the -Hyperledger fabric.* We recommend first running in chaincode development mode. - -## Getting started - -**Note:** This sample was prepared using Docker for Mac 1.12.0 - -* Prerequisite software to install: - - * [Docker](https://www.docker.com/products/overview) - * docker-compose (may be packaged with Docker) - -* Copy our [docker-compose.yml](https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/docker-compose.yml) file to a local directory: - -``` - curl -o docker-compose.yml https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/docker-compose.yml -``` - The docker-compose environment uses three Docker images. Two are published to - DockerHub. However, with the third, we provide you the source to build your own, - so that you can customize it to inject your application code for development. The following [Dockerfile](https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/Dockerfile) - is used to build the base **fabric-starter-kit** image and may be used as - a starting point for your own customizations. - -``` - curl -o Dockerfile https://raw.githubusercontent.com/hyperledger/fabric/master/examples/sdk/node/Dockerfile - docker build -t hyperledger/fabric-starter-kit:latest . -``` - -* 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. - - * to run as detached containers: - -``` - docker-compose up -d -``` - **note:** to see the logs for the `peer` container use the - `docker logs peer` command - - * to run in the foreground and see the log output in the current terminal - session: - -``` - docker-compose up -``` - - Both commands will start three Docker containers. To view the container - status use the `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. - -``` - docker ps -``` - You should see something similar to the following: - -``` - CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES - bb01a2fa96ef hyperledger/fabric-starter-kit "sh -c 'sleep 20; /op" About a minute ago Up 59 seconds starter - ec7572e65f12 hyperledger/fabric-peer "sh -c 'sleep 10; pee" About a minute ago Up About a minute peer - 118ef6da1709 hyperledger/fabric-membersrvc "membersrvc" About a minute ago Up About a minute membersrvc -``` - -* Start a terminal session in the **starter** container. This is where the -Node.js application is located. - - **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: - -``` - docker exec -it starter /bin/bash -``` - -* From the terminal session in the **starter** 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: - -``` - node app -``` - 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): - -``` - docker logs peer -``` - -* If you wish to run your own Node.js application using the pre-built Docker -images: - * use the directories in the `volumes` tag under **starter** 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. - -```yaml - volumes: - - ~/mytest:/user/mytest -``` - * copy or create and edit your application in the `~/mytest` directory as - stated in the `docker-compose.yml` `volumes` tag under **starter** container. - * run npm to install Hyperledger fabric Node.js SDK in the `mytest` directory: - -``` - npm install /opt/gopath/src/github.com/hyperledger/fabric-sdk-node -``` - * run the application from within the **starter** Docker container using the - following commands: - -``` - docker exec -it starter /bin/bash -``` - once in the shell, and assuming your Node.js application is called `app.js`: - -``` - cd /user/mytest - node app -``` -* 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 **starter** -container will persist. This will shutdown each of the containers and remove -the containers from Docker: - -``` - docker-compose down -``` - or if you wish to keep your changes and just stop the containers, which will - be restarted on the next `up` command: - -``` - docker-compose kill -``` - -## Further exploration - -If you wish, there are a number of chaincode examples nearby. -``` - cd $GOPATH/src/github.com/hyperledger/fabric/examples/chaincode -``` +If you are looking for the v0.6 Starter Kit, you can find it +[here](http://hyperledger-fabric.readthedocs.io/en/v0.6/starter/fabric-starter-kit/). diff --git a/mkdocs.yml b/mkdocs.yml index 6b17d12bef8..c6bf8399791 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,7 +24,7 @@ pages: - API's: - Chaincode APIs: API/ChaincodeAPI.md - - Core API: API/CoreAPI.md + - Command Line Interface: API/CLI.md - CA API: API/MemberServicesAPI.md - Fabric Developer: