[FAB-4962] CouchDB username/passwords for end to end

The example for the end to end Getting Started scenario
should allow CouchDB and the peer to be configured with
CouchDB username and password.

The proposed change to docker-compose-couch.yaml would allow
admin usernames and passwords to be added for couchdb and peer
docker images.

All parameters added to the script are left uninitialized.
This allows the script to run "as is" and the CouchDB containers
are created in "admin party" mode.  If the new variables are
populated, the CouchDB containers and peers are created with
usernames and passwords.

Formatting updates to ledger.rst - make code block from core.yaml
render properly and tag environment variables.

Change-Id: I39595a6cd15aed1eed0b10f5fad8a3e09b08b9e5
Signed-off-by: Chris Elder <[email protected]>
Signed-off-by: Nick Gaski <[email protected]>

docs/source/ledger.rst

@@ -71,7 +71,7 @@ concurrency control, and the state DB.
 State Database options
 ----------------------
 
-State database options include LevelDB and CouchDB (beta). LevelDB is the default key/value state
+State database options include LevelDB and CouchDB. LevelDB is the default key/value state
 database embedded in the peer process. CouchDB is an optional alternative external state database.
 Like the LevelDB key/value store, CouchDB can store any binary data that is modeled in chaincode
 (CouchDB attachment functionality is used internally for non-JSON binary data). But as a JSON
@@ -104,10 +104,64 @@ default embedded LevelDB, and move to CouchDB if you require the additional comp
 It is a good practice to model chaincode asset data as JSON, so that you have the option to perform
 complex rich queries if needed in the future.
 
-To enable CouchDB as the state database, configure the /fabric/sampleconfig/core.yaml ``stateDatabase``
-section.
+CouchDB Configuration
+----------------------
 
+CouchDB is enabled as the state database by changing the stateDatabase configuration option from
+goleveldb to CouchDB.   Additionally, the ``couchDBAddress`` needs to configured to point to the
+CouchDB to be used by the peer.  The username and password properties should be populated with
+an admin username and password if CouchDB is configured with a username and password.  Additional
+options are provided in the ``couchDBConfig`` section and are documented in place.  Changes to the
+*core.yaml* will be effective immediately after restarting the peer.
+
+You can also pass in docker environment variables to override core.yaml values, for example
+``CORE_LEDGER_STATE_STATEDATABASE`` and ``CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS``.
+
+Below is the ``stateDatabase`` section from *core.yaml*:
+
+.. code:: bash
+
+    state:
+      # stateDatabase - options are "goleveldb", "CouchDB"
+      # goleveldb - default state database stored in goleveldb.
+      # CouchDB - store state database in CouchDB
+      stateDatabase: goleveldb
+      couchDBConfig:
+         # It is recommended to run CouchDB on the same server as the peer, and
+         # not map the CouchDB container port to a server port in docker-compose.
+         # Otherwise proper security must be provided on the connection between
+         # CouchDB client (on the peer) and server.
+         couchDBAddress: couchdb:5984
+         # This username must have read and write authority on CouchDB
+         username:
+         # The password is recommended to pass as an environment variable
+         # during start up (e.g. LEDGER_COUCHDBCONFIG_PASSWORD).
+         # If it is stored here, the file must be access control protected
+         # to prevent unintended users from discovering the password.
+         password:
+         # Number of retries for CouchDB errors
+         maxRetries: 3
+         # Number of retries for CouchDB errors during peer startup
+         maxRetriesOnStartup: 10
+         # CouchDB request timeout (unit: duration, e.g. 20s)
+         requestTimeout: 35s
+         # Limit on the number of records to return per query
+         queryLimit: 10000
+
+
+CouchDB hosted in docker containers supplied with Hyperledger Fabric have the
+capability of setting the CouchDB username and password with environment
+variables passed in with the ``COUCHDB_USER`` and ``COUCHDB_PASSWORD`` environment
+variables using Docker Compose scripting.
+
+For CouchDB installations outside of the docker images supplied with Fabric, the
+*local.ini* file must be edited to set the admin username and password.
+
+Docker compose scripts only set the username and password at the creation of
+the container.  The *local.ini* file must be edited if the username or password
+is to be changed after creation of the container.
+
+.. note:: CouchDB peer options are read on each peer startup.
 
 .. Licensed under Creative Commons Attribution 4.0 International License
    https://creativecommons.org/licenses/by/4.0/
-

examples/e2e_cli/docker-compose-couch.yaml

@@ -9,6 +9,9 @@ services:
   couchdb0:
     container_name: couchdb0
     image: hyperledger/fabric-couchdb
+    environment:
+      - COUCHDB_USER=
+      - COUCHDB_PASSWORD=
     # Comment/Uncomment the port mapping if you want to hide/expose the CouchDB service,
     # for example map it to utilize Fauxton User Interface in dev environments.
     ports:
@@ -18,12 +21,17 @@ services:
     environment:
       - CORE_LEDGER_STATE_STATEDATABASE=CouchDB
       - CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=couchdb0:5984
+      - CORE_LEDGER_STATE_COUCHDBCONFIG_USERNAME=
+      - CORE_LEDGER_STATE_COUCHDBCONFIG_PASSWORD=
     depends_on:
       - couchdb0
 
   couchdb1:
     container_name: couchdb1
     image: hyperledger/fabric-couchdb
+    environment:
+      - COUCHDB_USER=
+      - COUCHDB_PASSWORD=
     # Comment/Uncomment the port mapping if you want to hide/expose the CouchDB service,
     # for example map it to utilize Fauxton User Interface in dev environments.
     ports:
@@ -33,12 +41,17 @@ services:
     environment:
       - CORE_LEDGER_STATE_STATEDATABASE=CouchDB
       - CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=couchdb1:5984
+      - CORE_LEDGER_STATE_COUCHDBCONFIG_USERNAME=
+      - CORE_LEDGER_STATE_COUCHDBCONFIG_PASSWORD=
     depends_on:
       - couchdb1
 
   couchdb2:
     container_name: couchdb2
     image: hyperledger/fabric-couchdb
+    environment:
+      - COUCHDB_USER=
+      - COUCHDB_PASSWORD=
     # Comment/Uncomment the port mapping if you want to hide/expose the CouchDB service,
     # for example map it to utilize Fauxton User Interface in dev environments.
     ports:
@@ -48,12 +61,17 @@ services:
     environment:
       - CORE_LEDGER_STATE_STATEDATABASE=CouchDB
       - CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=couchdb2:5984
+      - CORE_LEDGER_STATE_COUCHDBCONFIG_USERNAME=
+      - CORE_LEDGER_STATE_COUCHDBCONFIG_PASSWORD=
     depends_on:
       - couchdb2
 
   couchdb3:
     container_name: couchdb3
     image: hyperledger/fabric-couchdb
+    environment:
+      - COUCHDB_USER=
+      - COUCHDB_PASSWORD=
     # Comment/Uncomment the port mapping if you want to hide/expose the CouchDB service,
     # for example map it to utilize Fauxton User Interface in dev environments.
     ports:
@@ -63,5 +81,7 @@ services:
     environment:
       - CORE_LEDGER_STATE_STATEDATABASE=CouchDB
       - CORE_LEDGER_STATE_COUCHDBCONFIG_COUCHDBADDRESS=couchdb3:5984
+      - CORE_LEDGER_STATE_COUCHDBCONFIG_USERNAME=
+      - CORE_LEDGER_STATE_COUCHDBCONFIG_PASSWORD=
     depends_on:
       - couchdb3