caas review comments

Signed-off-by: Josh Horton <joshh@us.ibm.com>

docs/source/cc_basic.md

@@ -1,10 +1,10 @@
-# Running Chaincode as a Service on the Test Network
+# Running External Chaincode Builders
 
-The Fabric v2.4.1 chaincode-as-a-service feature is a novel, practical approach to running smart contracts. By comparison, the earlier method required the peer to orchestrate the complete lifecycle of the chaincode. This required the peer to have access to the Docker Daemon to create images, and to start containers. Java, Node.js and Go chaincode frameworks were explicitly known to the peer, including how they should be built and started.
+Fabric v2.4.1 external chaincode builders provide a practical approach to running smart contracts by enabling the peer to run external (to itself) commands to manage chaincode. By comparison, the earlier [deploying a smart contract to a channel](deploy_chaincode.html) method required the peer to orchestrate the complete lifecycle of the chaincode. This required the peer to have access to the Docker Daemon to create images and to start containers. Java, Node.js and Go chaincode frameworks were explicitly known to the peer, including how they should be built and started.
 
-As a result, the earlier method made it challenging to deploy chaincode into Kubernetes (K8s) style environments, and to run chaincode in any form of debug mode. Additionally, the code was rebuilt by the peer, introducing a degree of uncertainty about which dependencies had been installed.
+As a result, the traditional chaincode deployment method made it challenging to deploy chaincode into Kubernetes (K8s), or other environments where access to the Docker Daemon is restricted, and to run chaincode in any form of debug mode. Additionally, the code was usually rebuilt by the peer, requiring an external internet connection and introducing some uncertainty about which dependencies had been installed.
 
-The new chaincode-as-service method requires an administrator to orchestrate the chaincode build and deployment phase. Although this creates an additional step, it provides administrators with control over the process. The peer still requires a 'chaincode package' to be installed, but with no code - only information about where the chaincode is hosted is installed (such as Hostname, Port, and TLS configuration).
+The chaincode as a service method does require an administrator to orchestrate the chaincode build and deployment phase. Although this creates an additional step, it provides administrators with control over the process. The peer still requires a 'chaincode package' to be installed, but with no code - only information about where the chaincode is hosted is installed (such as hostname, port, and TLS configuration).
 
 ## Fabric v2.4.1 Improvements
 
@@ -14,7 +14,7 @@ The test network uses the latest Fabric release (v2.4.1), which facilitates usin
 - The `ccaasbuilder` applications are included in the binary tgz archive download for use in other circumstances. The `sampleconfig/core.yaml` is updated to refer to 'ccaasbuilder'.
 - The Fabric v2.4.1 Java chaincode removes the requirement to write a custom bootstrap main class (as implemented in the Node.js chaincode and planned for the go chaincode).
 
-(Note this core functionality is also available in earlier releases, but requires more configuration.)
+**NOTE:** This core functionality is also available in earlier releases, but with the requirements of writing the external chaincode code builder binaries and configuring the core.yaml correctly.
 
 ## End-to-end with the test-network
 
@@ -36,21 +36,21 @@ cd test-network
 ./network.sh up createChannel
 ```
 
-Variants of the next command, such as to use CouchDB or CAs, can be used without affecting the chaincode-as-a-service feature. The three keys steps are as follows:
+Variants of the next command, such as to use CouchDB or CAs, can be used without affecting the chaincode-as-a-service feature. The three keys steps are as follows, in no required order:
 
-1. Build a Docker image of the contract. Both `/asset-transfer-basic/chaincode-typescript` and `/asset-transfer-basic/chaincode-java` have been updated with Dockerfiles.
-2. Install, Approve and Commit a chaincode definition. This is unchanged, but the chaincode package contains connection information (hostname, port, TLS certificates), not code.
-3. Start the docker container(s) containing the contract
+1. Build a Docker image of the chaincode package, which contains information for determining where the chaincode containers (hosting one or more contracts) are running. Both `/asset-transfer-basic/chaincode-typescript` and `/asset-transfer-basic/chaincode-java` have been updated with Docker files.
+2. Install, approve, and commit a chaincode definition; these commands are run regardless of whether external chaincode builders are used. The chaincode package contains connection information (hostname, port, TLS certificates) only, with no code.
+3. Start the Docker container(s) containing the contract.
 
-The presented order of the prior steps is not mandatory, but the containers must be running before the first transaction is set by the peer. This could be on the `commit` if the `initRequired` flag is set.
+The containers must be running before the first transaction is committed by the peer. This could be on the `commit` if the `initRequired` flag is set.
 
 This sequence can be run as follows:
 
 ```bash
 ./network.sh deployCCAAS  -ccn basicts -ccp ../asset-transfer-basic/chaincode-typescript
 ```
 
-This is similar to the `deployCC` command in that it specifies the name and path. But it also requires the port for the chaincode container to use. Because each container is on the `fabric-test` network, changing the port can avoid collisions with other chaincode containers.
+This is similar to the `deployCC` command in that it specifies the name and path. Because each container is on the `fabric-test` network, changing the port can avoid collisions with other chaincode containers. If you run multiple services, the ports will need to change.
 
 If successful to this point, the smart contract (chaincode) should be starting in the monitoring window. There should be two containers running, one for `org1` and one for `org2`. The container names contain the organization, peer, and chaincode name.
 
@@ -171,16 +171,15 @@ The following prerequisites apply to debugging Node.js:
 
 The following prerequisites apply to debugging Java:
 
-- Port 800 is forwarded, which is the debug port for the JVM.
+- Port 8000 is forwarded, which is the debug port for the JVM.
 - `-e DEBUG=true` will trigger the node runtime to be started in debug mode. This is an example encoded in the `docker/docker-entrypoint.sh` script, which **for security purposes, should be considered for removal from production images**.
 - The `java` command option to start the debugger is `java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=0.0.0.0:8000 -jar /chaincode.jar`.  Note `0.0.0.0`, as the debug port, must be bound to all network adapters so the debugger can be attached from outside the container.
 
 ## Running with multiple peers
 
 In the earlier method, each peer that the chaincode is approved on will have a container running the chaincode. The '-as-a-service' approach requires achieving the same architecture.
 
-The `connection.json` contains the address of the running chaincode container, so it can be updated to ensure that each peer connects to a different container. However, as with the `connection.json` in the chaincode package, Fabric mandates that the package ID be consistent across all peers in an organization. To achieve this,
-the external builder supports a template capability. The context from this template is taken from the environment variable `CHAINCODE_AS_A_SERVICE_BUILDER_CONFIG` set on each peer.
+The `connection.json` contains the address of the running chaincode container, so it can be updated to ensure that each peer connects to a different container. However, as with the `connection.json` in the chaincode package, Fabric mandates that the package ID be consistent across all peers in an organization. To achieve this, the external builder supports a template capability. The context from this template is taken from the environment variable `CHAINCODE_AS_A_SERVICE_BUILDER_CONFIG` set on each peer.
 
 Define the address to be a template in `connection.json` as follows:
 

docs/source/cc_service.md

@@ -1,8 +1,8 @@
-# Chaincode as an external service
+# Running Chaincode as an External Service
 
-**Attention:** This page is for **advanced users of chaincode as an external service only. Proceed with caution.** New users of chaincode as a service should instead use the [Running Chaincode as Service on the Test Network](cc_basic.html) tutorial.
+**Attention: This page is for advanced users who choose to configure chaincode as a service external to the Fabric peer. Proceed with caution!** New users of chaincode should start with [deploying a smart contract to a channel](deploy_chaincode.html) before proceeding with this tutorial.
 
-Fabric v2.0 supports chaincode deployment and execution outside of Fabric that enables users to manage a chaincode runtime independently of the peer. This facilitates deployment of chaincode on Fabric cloud deployments such as Kubernetes. Instead of building and launching the chaincode on every peer, chaincode can now run as a service whose lifecycle is managed outside of Fabric. This capability leverages the Fabric v2.0 external builder and launcher functionality which enables operators to extend a peer with programs to build, launch, and discover chaincode. Before reading this topic you should become familiar with the [External Builder and Launcher](./cc_launcher.html) content.
+Fabric v2.0 supports chaincode deployment and execution outside of Fabric that enables users to manage a chaincode runtime independently of the peer. This facilitates deployment of chaincode on Fabric cloud deployments, such as Kubernetes. Instead of building and launching the chaincode on every peer, chaincode can be run as a service, external to Fabric. This capability leverages the Fabric v2.0 external builder and launcher functionality, which enables operators to extend a peer with programs to build, launch, and discover chaincode. Before reading this topic you should become familiar with the [External Builder and Launcher](./cc_launcher.html) content.
 
 Prior to the availability of the external builders, the chaincode package content was required to be a set of source code files for a particular language which could be built and launched as a chaincode binary. The new external build and launcher functionality now allows users to optionally customize the build process. With respect to running the chaincode as an external service, the build process allows you to specify the endpoint information of the server where the chaincode is running. Hence the package simply consists of the externally running chaincode server endpoint information and TLS artifacts for secure connection. TLS is optional but highly recommended for all environments except a simple test environment.
 

docs/source/tutorials.rst

@@ -34,9 +34,9 @@ Finally, we provide an introduction to how to write a basic smart contract,
    :caption: Tutorials
 
    test_network
-   cc_basic.md
    deploy_chaincode.md
    write_first_app
+   cc_basic.md
    private_data_tutorial
    secured_asset_transfer/secured_private_asset_transfer_tutorial.md
    couchdb_tutorial