diff --git a/docs/abstract_v1.md b/docs/abstract_v1.md new file mode 100644 index 00000000000..ea0dd563d64 --- /dev/null +++ b/docs/abstract_v1.md @@ -0,0 +1,32 @@ +# HYPERLEDGER FABRIC v1.0 + +Hyperledger fabric is a platform that enables the delivery of a secure, robust, permissioned blockchain for the enterprise that incorporates a byzantine fault tolerant consensus. We have learned much as we progressed through the v0.6-preview release. In particular, that in order to provide for the scalability and confidentiality needs of many use cases, a refactoring of the architecture was needed. The v0.6-preview release will be the final (barring any bug fixes) release based upon the original architecture. + +Hyperledger fabric's v1.0 architecture has been designed to address two vital enterprise-grade requirements – **security** and **scalability**. Businesses and organizations can leverage this new architecture to execute confidential transactions on networks with shared or common assets – e.g. supply chain, FOREX market, healthcare, etc. The progression to v1.0 will be incremental, with myriad windows for community members to contribute code and start curating the fabric to fit specific business needs. + +## WHERE WE ARE: + +The current implementation involves every validating peer shouldering the responsibility for the full gauntlet of network functionality. They execute transactions, perform consensus, and maintain the shared ledger. Not only does this configuration lay a huge computational burden on each peer, hindering scalability, but it also constricts important facets of privacy and confidentiality. Namely, there is no mechanism to “channel” or “silo” confidential transactions. Every peer can see the logic for every transaction. + +## WHERE WE'RE GOING + +The new architecture introduces a clear functional separation of peer roles, and allows a transaction to pass through the network in a structured and modularized fashion. The peers are diverged into two distinct roles – Endorser & Committer. As an endorser, the peer will simulate the transaction and ensure that the outcome is both deterministic and stable. As a committer, the peer will validate the integrity of a transaction and then append to the ledger. Now confidential transactions can be sent to specific endorsers and their correlating committers, without the network being made cognizant of the transaction. Additionally, policies can be set to determine what levels of “endorsement” and “validation” are acceptable for a specific class of transactions. A failure to meet these thresholds would simply result in a transaction being withdrawn, rather than imploding or stagnating the entire network. This new model also introduces the possibility for more elaborate networks, such as a foreign exchange market. Entities may need to only participate as endorsers for their transactions, while leaving consensus and commitment (i.e. settlement in this scenario) to a trusted third party such as a clearing house. + +The consensus process (i.e. algorithmic computation) is entirely abstracted from the peer. This modularity not only provides a powerful security layer – the consenting nodes are agnostic to the transaction logic – but it also generates a framework where consensus can become pluggable and scalability can truly occur. There is no longer a parallel relationship between the number of peers in a network and the number of consenters. Now networks can grow dynamically (i.e. add endorsers and committers) without having to add corresponding consenters, and exist in a modular infrastructure designed to support high transaction throughput. Moreover, networks now have the capability to completely liberate themselves from the computational and legal burden of consensus by tapping into a pre-existing consensus cloud. + +As v1.0 manifests, we will see the foundation for interoperable blockchain networks that have the ability to scale and transact in a manner adherent with regulatory and industry standards. Watch how fabric v1.0 and the Hyperledger Project are building a true blockchain for business - + +[![HYPERLEDGERv1.0_ANIMATION](http://img.youtube.com/vi/EKa5Gh9whgU/0.jpg)](http://www.youtube.com/watch?v=EKa5Gh9whgU) + +## HOW TO CONTRIBUTE + +Use the following links to explore upcoming additions to fabric's codebase that will spawn the capabilities in v1.0: + +* Familiarize yourself with the [guidelines for code contributions](CONTRIBUTING.md) to this project. **Note**: In order to participate in the development of the Hyperledger fabric project, you will need an [LF account](Gerrit/lf-account.md). This will give you single +sign-on to JIRA and Gerrit. +* Explore the design document for the new [architecture](https://github.com/hyperledger-archives/fabric/wiki/Next-Consensus-Architecture-Proposal) +* Explore [JIRA](https://jira.hyperledger.org/projects/FAB/issues/) for open Hyperledger fabric issues. +* Explore the [JIRA](https://jira.hyperledger.org/projects/FAB/issues/) backlog for upcoming Hyperledger fabric issues. +* Explore [JIRA](https://jira.hyperledger.org/issues/?filter=10147) for Hyperledger fabric issues tagged with "help wanted." +* Explore the [source code](https://github.com/hyperledger/fabric) +* Explore the [documentation](http://hyperledger-fabric.readthedocs.io/en/latest/) diff --git a/docs/starter/fabric-starter-kit.md b/docs/starter/fabric-starter-kit.md new file mode 100644 index 00000000000..7d199ad1281 --- /dev/null +++ b/docs/starter/fabric-starter-kit.md @@ -0,0 +1,170 @@ +# 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. + +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](../nodeSDK/app-overview.md) 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. + +## Further exploration + +If you wish, there are a number of chaincode examples near by. +``` + cd ../../chaincode +``` +## 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 +``` diff --git a/mkdocs.yml b/mkdocs.yml index b81da566fdc..73b7f9e0ff3 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -10,6 +10,9 @@ pages: - Protocol Spec: protocol-spec.md - Usecases: biz/usecases.md +- Starter Kit: + - Starter Kit: starter/fabric-starter-kit.md + - Installation and setup: - Chaincode or Application Developer Setup: Setup/Chaincode-setup.md - Java Chaincode Setup: Setup/JAVAChaincode.md @@ -25,6 +28,7 @@ pages: - System Chaincode: SystemChaincodes/noop.md - Fabric Developer: + - v1.0 Preview: abstract_v1.md - Contributing: CONTRIBUTING.md - Getting an Account: Gerrit/lf-account.md - Gerrit: Gerrit/gerrit.md @@ -49,6 +53,14 @@ pages: - Attributes: tech/attributes.md - Best Practices: tech/best-practices.md +- NodeSDK: + - App-developer-env-setup: nodeSDK/app-developer-env-setup.md + - App-Overview: nodeSDK/app-overview.md + - Node-SDK-guide: nodeSDK/node-sdk-guide.md + - Node-SDK-indepth: nodeSDK/node-sdk-indepth.md + - Sample-Standalone-app: nodeSDK/sample-standalone-app.md + - Sample-web-app: nodeSDK/sample-web-app.md + markdown_extensions: - extra - tables