fix #59 and #64

Author: binhn

dev-setup/devnet-setup.md

@@ -2,34 +2,53 @@
 
 This document covers setting up an Openchain network on your local machine for development using Docker containers.
 
-All commands should be run from within the Vagrant environment described [here](https://github.com/openblockchain/obc-docs/blob/master/dev-setup/devenv.md).
+All commands should be run from within the Vagrant environment described in [Setting Up Development Environment](https://github.com/openblockchain/obc-docs/blob/master/dev-setup/devenv.md).
 
-**Note:** When running with security enabled, first modify the [openchain.yaml](https://github.com/openblockchain/obc-peer/blob/master/openchain.yaml) to set the security.enabled setting to 'true' before building the peer executable. Furthermore, follow the security setup instructions described [here](https://github.com/openblockchain/obc-docs/blob/master/api/SandboxSetup.md#security-setup-optional) to set up the CA server and log in registered users before sending chaincode transactions.
+**Note:** When running with security enabled, follow the security setup instructions described in [Chaincode Development](https://github.com/openblockchain/obc-docs/blob/master/api/SandboxSetup.md#security-setup-optional) to set up the CA server and log in registered users before sending chaincode transactions.
 
-### Setting up an Openchain Docker image
-First clean out any active Openchain containers (peer and chaincode) using "docker ps -a" and "docker rm" commands. Second, remove any old Openchain images with "docker images" and "docker rmi" commands.
+### Setting up Docker image
+To create a Docker image for Open Blockchain, named `openchain`,
+first clean out any active `openchain` containers (peer and chaincode) using `docker ps -a` and `docker rm` commands. Second, remove any old `openchain` images with `docker images` and `docker rmi` commands.
 
-Now we are ready to build a new Openchain docker image:
+Now we are ready to build a new `openchain` docker image:
 
+```
     cd $GOPATH/src/github.com/openblockchain/obc-peer/openchain/container
     go test -run BuildImage_Peer
+```
 
-Check the available images, and you should see "openchain-peer" image.
+Check the available images again with `docker images`, and you should see `openchain-peer` image.
 
 ### Starting up validating peers
-Find out which IP address your docker0 interface is on with *ip add* command. For example, your output might contain something like *inet 172.17.0.1/16 scope global docker0*. That means docker0 interface is on IP address 172.17.0.1. Use that IP address for the OPENCHAIN_VM_ENDPOINT option.
+From the Vagrant environment, find out which IP address your docker0 interface is on with `ip add` command. For example,
+
+```
+vagrant@vagrant-ubuntu-trusty-64:/opt/gopath/src/github.com/openblockchain/obc-peer$ ip add
+
+<<< detail removed >>>
+
+3: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN group default
+    link/ether 02:42:ad:be:70:cb brd ff:ff:ff:ff:ff:ff
+    inet 172.17.0.1/16 scope global docker0
+       valid_lft forever preferred_lft forever
+    inet6 fe80::42:adff:febe:70cb/64 scope link
+       valid_lft forever preferred_lft forever
+```
+
+Your output might contain something like `inet 172.17.0.1/16 scope global docker0`. That means docker0 interface is on IP address 172.17.0.1. Use that IP address for the `OPENCHAIN_VM_ENDPOINT` option. For more information on the environment variables, see `openchain.yaml` configuration file in the `obc-peer` repository.
 
-The ID value of OPENCHAIN_PEER_ID must be lowercase since we use the ID as part of chaincode containers we build, and docker does not accept uppercase. The ID must also be unique for each validating peer.
+The ID value of `OPENCHAIN_PEER_ID` must be lowercase since we use the ID as part of chaincode containers we build, and docker does not accept uppercase. The ID must also be unique for each validating peer.
 
-We are also using the default consensus, called NOOPS, which doesn't really do consensus. If you want to use some other consensus plugin, see note 1 below.
+By default, we are using a consensus plugin called `NOOPS`, which doesn't really do consensus. If you want to use some other consensus plugin, see Using Consensus Plugin section at the end of the document.
 
-Start up the first validating peer:
+#### Start up the first validating peer:
 
 ```
 docker run --rm -it -e OPENCHAIN_VM_ENDPOINT=http://172.17.0.1:4243 -e OPENCHAIN_PEER_ID=vp1 -e OPENCHAIN_PEER_ADDRESSAUTODETECT=true openchain-peer obc-peer peer
 ```
 
-Start up the second validating peer: We need to get the IP address of the first validating peer, which will act as the root node that the new peer will connect to. The address is printed out on the terminal window of the first peer (eg 172.17.0.2). We'll use "vp2" as the ID for the second validating peer.
+####Start up the second validating peer:
+We need to get the IP address of the first validating peer, which will act as the root node that the new peer will connect to. The address is printed out on the terminal window of the first peer (eg 172.17.0.2). We'll use "vp2" as the ID for the second validating peer.
 
 ```
 docker run --rm -it -e OPENCHAIN_VM_ENDPOINT=http://172.17.0.1:4243 -e OPENCHAIN_PEER_ID=vp2 -e OPENCHAIN_PEER_ADDRESSAUTODETECT=true -e OPENCHAIN_PEER_DISCOVERY_ROOTNODE=172.17.0.2:30303 openchain-peer obc-peer peer
@@ -84,3 +103,15 @@ With security enabled, modify the command as follows:
 ```
 ./obc-peer chaincode query -u jim -l golang -n <name_value_returned_from_deploy_command> -c '{"Function": "query", "Args": ["a"]}'
 ```
+
+### Using Consensus Plugin
+A consensus plugin might require some specific configuration that you need to set up. For example, to use Byzantine consensus plugin provided as part of Open Blockchain, perform the following configuration:
+
+1. In `openchain.yaml`, set the `peer.validator.consensus` value to `obcpbft`
+2. In `openchain.yaml`, make sure the `peer.id` is set sequentially as `vpX` where `X` is an integer that starts from `0` and goes to `N-1`. For example, with 4 validating peers, set the `peer.id` to`vp0`, `vp1`, `vp2`, `vp3`.
+3. In `consensus/obcpbft/config.yaml`, set the `general.mode` value to either `classic`, `batch`, or `sieve`, and the `general.N` value to the number of validating peers on the network (if you do `batch`, also set `general.batchsize` to the number of transactions per batch)
+4. In `consensus/obcpbft/config.yaml`, optionally set timer values for the batch period (`general.timeout.batch`), the acceptable delay between request and execution (`general.timeout.request`), and for view-change (`general.timeout.viewchange`)
+
+See `openchain.yaml` and `consensus/obcpbft/config.yaml` for more detail.
+
+All of these setting may be overriden via the command line environment variables, eg. `OPENCHAIN_PEER_VALIDATOR_CONSENSUS=obcpbft` or `OPENCHAIN_OBCPBFT_GENERAL_MODE=sieve`