Merge "[FAB-2565] Example docker-compose with CouchDB"

examples/e2e_cli/configtx.yaml

@@ -131,7 +131,7 @@ Orderer: &OrdererDefaults
         - orderer0:7050
 
     # Batch Timeout: The amount of time to wait before creating a batch
-    BatchTimeout: 10s
+    BatchTimeout: 2s
 
     # Batch Size: Controls the number of messages batched into a block
     BatchSize:

examples/e2e_cli/docker-compose.yaml

@@ -24,6 +24,20 @@ services:
     ports:
       - 7050:7050
 
+## To enable CouchDB as state database, uncomment the following sections of this file:
+## 1) couchdb containers
+## 2) peer environment variables CORE_LEDGER_STATE_STATEDATABASE and
+##    CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS
+## 3) couch container names in "depends_on" section
+
+#  couchdb0:
+#    container_name: couchdb0
+#    image: hyperledger/fabric-couchdb
+##   Uncomment the port mapping if you want to expose the CouchDB service,
+##   for example to utilize Fauxton User Interface in dev environments.
+#    ports:
+#      - "5984:5984"
+
   peer0:
     container_name: peer0
     extends:
@@ -33,12 +47,14 @@ services:
       - CORE_PEER_ID=peer0
       - CORE_PEER_ADDRESS=peer0:7051
       - CORE_PEER_GOSSIP_EXTERNALENDPOINT=peer0:7051
-      #- CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer0:7050
+      # - CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer0:7050
       - CORE_PEER_LOCALMSPID=Org0MSP
       - CORE_PEER_TLS_CERT_FILE=/etc/hyperledger/fabric/msp/sampleconfig/signcerts/peer0Signer.pem
       - CORE_PEER_TLS_KEY_FILE=/etc/hyperledger/fabric/msp/sampleconfig/keystore/peer0Signer.pem
       - CORE_PEER_TLS_ROOTCERT_FILE=/etc/hyperledger/fabric/msp/sampleconfig/cacerts/peerOrg0.pem
-      #- CORE_PEER_TLS_SERVERHOSTOVERRIDE=peer0
+      # - CORE_PEER_TLS_SERVERHOSTOVERRIDE=peer0
+      # - CORE_LEDGER_STATE_STATEDATABASE=CouchDB
+      # - CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=couchdb0:5984
     volumes:
         - /var/run/:/host/var/run/
         - ./crypto/peer/peer0/localMspConfig:/etc/hyperledger/fabric/msp/sampleconfig
@@ -47,6 +63,15 @@ services:
       - 7053:7053
     depends_on:
       - orderer0
+      # - couchdb0
+
+#  couchdb1:
+#    container_name: couchdb1
+#    image: hyperledger/fabric-couchdb
+##   Uncomment the port mapping if you want to expose the CouchDB service,
+##   for example to utilize Fauxton User Interface in dev environments.
+#    ports:
+#      - "6984:5984"
 
   peer1:
     container_name: peer1
@@ -58,12 +83,14 @@ services:
       - CORE_PEER_ADDRESS=peer1:7051
       - CORE_PEER_GOSSIP_EXTERNALENDPOINT=peer1:7051
       - CORE_PEER_GOSSIP_BOOTSTRAP=peer0:7051
-      #- CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer0:7050
+      # - CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer0:7050
       - CORE_PEER_LOCALMSPID=Org0MSP
       - CORE_PEER_TLS_CERT_FILE=/etc/hyperledger/fabric/msp/sampleconfig/signcerts/peer1Signer.pem
       - CORE_PEER_TLS_KEY_FILE=/etc/hyperledger/fabric/msp/sampleconfig/keystore/peer1Signer.pem
       - CORE_PEER_TLS_ROOTCERT_FILE=/etc/hyperledger/fabric/msp/sampleconfig/cacerts/peerOrg0.pem
-      #- CORE_PEER_TLS_SERVERHOSTOVERRIDE=peer1
+      # - CORE_PEER_TLS_SERVERHOSTOVERRIDE=peer1
+      # - CORE_LEDGER_STATE_STATEDATABASE=CouchDB
+      # - CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=couchdb1:5984
     volumes:
         - /var/run/:/host/var/run/
         - ./crypto/peer/peer1/localMspConfig:/etc/hyperledger/fabric/msp/sampleconfig
@@ -73,6 +100,15 @@ services:
     depends_on:
       - orderer0
       - peer0
+      # - couchdb1
+
+#  couchdb2:
+#    container_name: couchdb2
+#    image: hyperledger/fabric-couchdb
+##   Uncomment the port mapping if you want to expose the CouchDB service,
+##   for example to utilize Fauxton User Interface in dev environments.
+#    ports:
+#      - "7984:5984"
 
   peer2:
     container_name: peer2
@@ -90,6 +126,8 @@ services:
       - CORE_PEER_TLS_KEY_FILE=/etc/hyperledger/fabric/msp/sampleconfig/keystore/peer2Signer.pem
       - CORE_PEER_TLS_ROOTCERT_FILE=/etc/hyperledger/fabric/msp/sampleconfig/admincerts/peerOrg1.pem
       #- CORE_PEER_TLS_SERVERHOSTOVERRIDE=peer2
+      # - CORE_LEDGER_STATE_STATEDATABASE=CouchDB
+      # - CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=couchdb2:5984
     volumes:
         - /var/run/:/host/var/run/
         - ./crypto/peer/peer2/localMspConfig:/etc/hyperledger/fabric/msp/sampleconfig
@@ -100,6 +138,15 @@ services:
       - orderer0
       - peer0
       - peer1
+      # - couchdb2
+
+#  couchdb3:
+#    container_name: couchdb3
+#    image: hyperledger/fabric-couchdb
+##   Uncomment the port mapping if you want to expose the CouchDB service,
+##   for example to utilize Fauxton User Interface in dev environments.
+#    ports:
+#      - "8984:5984"
 
   peer3:
     container_name: peer3
@@ -111,12 +158,14 @@ services:
       - CORE_PEER_ADDRESS=peer3:7051
       - CORE_PEER_GOSSIP_EXTERNALENDPOINT=peer3:7051
       - CORE_PEER_GOSSIP_BOOTSTRAP=peer0:7051
-      #- CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer0:7050
+      # - CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer0:7050
       - CORE_PEER_LOCALMSPID=Org1MSP
       - CORE_PEER_TLS_CERT_FILE=/etc/hyperledger/fabric/msp/sampleconfig/signcerts/peer3Signer.pem
       - CORE_PEER_TLS_KEY_FILE=/etc/hyperledger/fabric/msp/sampleconfig/keystore/peer3Signer.pem
       - CORE_PEER_TLS_ROOTCERT_FILE=/etc/hyperledger/fabric/msp/sampleconfig/cacerts/peerOrg1.pem
-      #- CORE_PEER_TLS_SERVERHOSTOVERRIDE=peer3
+      # - CORE_PEER_TLS_SERVERHOSTOVERRIDE=peer3
+      # - CORE_LEDGER_STATE_STATEDATABASE=CouchDB
+      # - CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=couchdb3:5984
     volumes:
         - /var/run/:/host/var/run/
         - ./crypto/peer/peer3/localMspConfig:/etc/hyperledger/fabric/msp/sampleconfig
@@ -128,6 +177,7 @@ services:
       - peer0
       - peer1
       - peer2
+      # - couchdb3
 
   cli:
     container_name: cli
@@ -141,15 +191,15 @@ services:
       - CORE_NEXT=true
       - CORE_PEER_ID=cli
       - CORE_PEER_ENDORSER_ENABLED=true
-      #- CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer0:7050
+      # - CORE_PEER_COMMITTER_LEDGER_ORDERER=orderer0:7050
       - CORE_PEER_ADDRESS=peer0:7051
       - CORE_PEER_GOSSIP_IGNORESECURITY=true
       - CORE_PEER_LOCALMSPID=Org0MSP
       - CORE_PEER_TLS_ENABLED=true
       - CORE_PEER_TLS_CERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peer/peer0/localMspConfig/signcerts/peer0Signer.pem
       - CORE_PEER_TLS_KEY_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peer/peer0/localMspConfig/keystore/peer0Signer.pem
       - CORE_PEER_TLS_ROOTCERT_FILE=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peer/peer0/localMspConfig/cacerts/peerOrg0.pem
-      #- CORE_PEER_TLS_SERVERHOSTOVERRIDE=peer0
+      # - CORE_PEER_TLS_SERVERHOSTOVERRIDE=peer0
       - CORE_PEER_MSPCONFIGPATH=/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/peer/peer0/localMspConfig
 
     working_dir: /opt/gopath/src/github.com/hyperledger/fabric/peer
@@ -158,6 +208,7 @@ services:
     volumes:
         - /var/run/:/host/var/run/
         - ./examples/:/opt/gopath/src/github.com/hyperledger/fabric/examples/
+        - ../chaincode/go/:/opt/gopath/src/github.com/hyperledger/fabric/examples/chaincode/go
         - ./crypto:/opt/gopath/src/github.com/hyperledger/fabric/peer/crypto/
         - ./scripts:/opt/gopath/src/github.com/hyperledger/fabric/peer/scripts/
     depends_on:

examples/e2e_cli/end-to-end.rst

@@ -649,6 +649,165 @@ run!
 
     rm -rf /var/hyperledger/*
 
+Using CouchDB
+-------------
+
+The state database can be switched from the default (goleveldb) to CouchDB.
+The same chaincode functions are available with CouchDB, however, there is the
+added ability to perform rich and complex queries against the state database
+data content contingent upon the chaincode data being modeled as JSON.
+
+To use CouchDB instead of the default database (goleveldb), follow the same
+procedure in the **Prerequisites** section, and additionally perform the
+following two steps to enable the CouchDB containers and associate each peer
+container with a CouchDB container:
+
+-  Make the CouchDB image.
+
+   .. code:: bash
+
+       # make sure you are in the /fabric directory
+       make couchdb
+
+-  Open the ``fabric/examples/e2e_cli/docker-compose.yaml`` and un-comment
+   all commented statements relating to CouchDB containers and peer container
+   use of CouchDB. These instructions are are also outlined in the
+   same ``docker-compose.yaml`` file. Search the file for 'couchdb' (case insensitive) references.
+
+*chaincode_example02* should now work using CouchDB underneath.
+
+***Note***: If you choose to implement mapping of the fabric-couchdb container
+port to a host port, please make sure you are aware of the security
+implications. Mapping of the port in a development environment allows the
+visualization of the database via the CouchDB web interface (Fauxton).
+Production environments would likely refrain from implementing port mapping in
+order to restrict outside access to the CouchDB containers.
+
+You can use *chaincode_example02* chaincode against the CouchDB state database
+using the steps outlined above, however in order to exercise the query
+capabilities you will need to use a chaincode that has data modeled as JSON,
+(e.g. *marbles02*). You can locate the *marbles02* chaincode in the
+``fabric/examples/chaincode/go`` directory.
+
+Install, instantiate, invoke, and query *marbles02* chaincode by following the
+same general steps outlined above for *chaincode_example02* in the **Manually
+create the channel and join peers through CLI** section . After the **Join
+channel** step, use the following steps to interact with the *marbles02*
+chaincode:
+
+-  Install and instantiate the chaincode in ``peer0`` (replace ``$ORDERER_IP``
+   with the IP address of the orderer. One way to find the address is with the
+   command ``docker inspect orderer | grep \"IPAddress\"``):
+
+   .. code:: bash
+
+       peer chaincode install -o $ORDERER_IP:7050 -n marbles -v 1.0 -p github.com/hyperledger/fabric/examples/chaincode/go/marbles02
+       peer chaincode instantiate -o $ORDERER_IP:7050 -C $mychannel -n marbles -v 1.0 -p github.com/hyperledger/fabric/examples/chaincode/go/marbles02 -c '{"Args":["init"]}' -P "OR      ('Org0MSP.member','Org1MSP.member')"
+
+-  Create some marbles and move them around:
+
+   .. code:: bash
+
+        peer chaincode invoke -o $ORDERER_IP:7050  -C mychannel -n marbles -c '{"Args":["initMarble","marble1","blue","35","tom"]}'
+        peer chaincode invoke -o $ORDERER_IP:7050  -C mychannel -n marbles -c '{"Args":["initMarble","marble2","red","50","tom"]}'
+        peer chaincode invoke -o $ORDERER_IP:7050  -C mychannel -n marbles -c '{"Args":["initMarble","marble3","blue","70","tom"]}'
+        peer chaincode invoke -o $ORDERER_IP:7050  -C mychannel -n marbles -c '{"Args":["transferMarble","marble2","jerry"]}'
+        peer chaincode invoke -o $ORDERER_IP:7050  -C mychannel -n marbles -c '{"Args":["transferMarblesBasedOnColor","blue","jerry"]}'
+        peer chaincode invoke -o $ORDERER_IP:7050  -C mychannel -n marbles -c '{"Args":["delete","marble1"]}'
+
+
+
+-  If you chose to activate port mapping, you can now view the state database
+   through the CouchDB web interface (Fauxton) by opening a browser and
+   navigating to one of the two URLs below.
+
+   For containers running in a vagrant environment:
+
+   ```http://localhost:15984/_utils```
+
+   For non-vagrant environment, use the port address that was mapped in CouchDB
+   container specification:
+
+   ```http://localhost:5984/_utils```
+
+   You should see a database named ``mychannel`` and the documents
+   inside it.
+
+-  You can run regular queries from the `cli` (e.g. reading ``marble2``):
+
+   .. code:: bash
+
+      peer chaincode query -o $ORDERER_IP:7050 -C mychannel -n marbles -c '{"Args":["readMarble","marble2"]}'
+
+
+   You should see the details of ``marble2``:
+
+   .. code:: bash
+
+       Query Result: {"color":"red","docType":"marble","name":"marble2","owner":"jerry","size":50}
+
+
+   Retrieve the history of ``marble1``:
+
+   .. code:: bash
+
+      peer chaincode query -o $ORDERER_IP:7050 -C mychannel -n marbles -c '{"Args":["getHistoryForMarble","marble1"]}'
+
+   You should see the transactions on ``marble1``:
+
+   .. code:: bash
+
+      Query Result: [{"TxId":"1c3d3caf124c89f91a4c0f353723ac736c58155325f02890adebaa15e16e6464", "Value":{"docType":"marble","name":"marble1","color":"blue","size":35,"owner":"tom"}},{"TxId":"755d55c281889eaeebf405586f9e25d71d36eb3d35420af833a20a2f53a3eefd", "Value":{"docType":"marble","name":"marble1","color":"blue","size":35,"owner":"jerry"}},{"TxId":"819451032d813dde6247f85e56a89262555e04f14788ee33e28b232eef36d98f", "Value":}]
+
+
+
+-  You can also perform rich queries on the data content, such as querying marble fields by owner ``jerry``:
+
+   .. code:: bash
+
+      peer chaincode query -o $ORDERER_IP:7050 -C myc1 -n marbles -c '{"Args":["queryMarblesByOwner","jerry"]}'
+
+   The output should display the two marbles owned by ``jerry``:
+
+   .. code:: bash
+
+       Query Result: [{"Key":"marble2", "Record":{"color":"red","docType":"marble","name":"marble2","owner":"jerry","size":50}},{"Key":"marble3", "Record":{"color":"blue","docType":"marble","name":"marble3","owner":"jerry","size":70}}]
+
+   Query by field ``owner`` where the value is ``jerry``:
+
+   .. code:: bash
+
+      peer chaincode query -o $ORDERER_IP:7050 -C myc1 -n marbles -c '{"Args":["queryMarbles","{\"selector\":{\"owner\":\"jerry\"}}"]}'
+
+   The output should display:
+
+   .. code:: bash
+
+       Query Result: [{"Key":"marble2", "Record":{"color":"red","docType":"marble","name":"marble2","owner":"jerry","size":50}},{"Key":"marble3", "Record":{"color":"blue","docType":"marble","name":"marble3","owner":"jerry","size":70}}]
+
+A Note on Data Persistence
+--------------------------
+
+If data persistence is desired on the peer container or the CouchDB container,
+one option is to mount a directory in the docker-host into a relevant directory
+in the container. For example, you may add the following two lines in
+the peer container specification in the ``docker-compose.yaml`` file:
+
+   .. code:: bash
+
+       volumes:
+        - /var/hyperledger/peer0:/var/hyperledger/production
+
+
+For the CouchDB container, you may add the following two lines in the CouchDB
+container specification:
+
+   .. code:: bash
+
+       volumes:
+        - /var/hyperledger/couchdb0:/opt/couchdb/data
+
+
 Troubleshooting
 ---------------