[CORDA-2560] Add upgrade notes for custom configuration and improve cordapp config… (#4730)

* Add upgrade notes for custom configuration and improve cordapp configuration documentation.

* Address review comments

* Couple of minor nitpicks

docs/README.md

@@ -0,0 +1,8 @@
+# Corda Documentation Build
+
+To run the Corda Documentation build run ``./gradlew makeDocs``
+
+Note: In order to run the documentation build you will need Docker installed.
+
+Windows users: If this task fails because Docker can't find make-docsite.sh, go to Settings > Shared Drives in the Docker system tray
+agent, make sure the relevant drive is shared, and click 'Reset credentials'.

docs/source/app-upgrade-notes.rst

@@ -24,7 +24,7 @@ from the new features in the latest release.
    :depth: 3
 
 Step 1. Switch any RPC clients to use the new RPC library
-----------------------------------------------------------
+---------------------------------------------------------
 
 Although the RPC API is backwards compatible with Corda 3, the RPC wire protocol isn't. Therefore RPC clients like web servers need to be
 updated in lockstep with the node to use the new version of the RPC library. Corda 4 delivers RPC wire stability and therefore in future you
@@ -117,7 +117,44 @@ starting from 1.
 If you use the finance demo app, you should adjust your dependencies so you depend on the finance-contracts
 and finance-workflows artifacts from your own contract and workflow JAR respectively.
 
-Step 4. Security: Upgrade your use of FinalityFlow
+Step 4. Remove any custom configuration from the node.conf
+----------------------------------------------------------
+
+CorDapps can no longer access custom configuration items in the ``node.conf`` file. Any custom CorDapp configuration should be added to a
+CorDapp configuration file. The Node's configuration will not be accessible. CorDapp configuration files should be placed in the
+`config` subdirectory of the Node's `cordapps` folder. The name of the file should match the name of the JAR of the CorDapp (eg; if your
+CorDapp is called ``hello-0.1.jar`` the configuration file needed would be ``cordapps/config/hello-0.1.conf``).
+
+If you are using the ``extraConfig`` of a ``node`` in the ``deployNodes`` Gradle task to populate custom configuration for testing, you will need
+to make the following change so that:
+
+.. sourcecode:: groovy
+
+    task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
+        node {
+            name "O=Bank A,L=London,C=GB"c
+            ...
+            extraConfig = [ 'some.extra.config' : '12345' ]
+        }
+    }
+
+Would become:
+
+.. sourcecode:: groovy
+
+    task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
+        node {
+            name "O=Bank A,L=London,C=GB"c
+            ...
+            projectCordapp {
+                config "some.extra.config=12345"
+            }
+        }
+    }
+
+See :ref:`cordapp_configuration_files_ref` for more information.
+
+Step 5. Security: Upgrade your use of FinalityFlow
 --------------------------------------------------
 
 The previous ``FinalityFlow`` API is insecure. It doesn't have a receive flow, so requires counterparty nodes to accept any and
@@ -231,7 +268,7 @@ You may already be using ``waitForLedgerCommit`` in your responder flow for the
 Now that it's calling ``ReceiveFinalityFlow``, which effectively does the same thing, this is no longer necessary. The call to
 ``waitForLedgerCommit`` should be removed.
 
-Step 5. Security: Upgrade your use of SwapIdentitiesFlow
+Step 6. Security: Upgrade your use of SwapIdentitiesFlow
 --------------------------------------------------------
 
 The :ref:`confidential_identities_ref` API is experimental in Corda 3 and remains so in Corda 4. In this release, the ``SwapIdentitiesFlow``
@@ -239,7 +276,7 @@ has been adjusted in the same way as ``FinalityFlow`` above, to close problems w
 outside of other flow context. Old code will still work, but it is recommended to adjust your call sites so a session is passed into
 the ``SwapIdentitiesFlow``.
 
-Step 6. Possibly, adjust test code
+Step 7. Possibly, adjust test code
 ----------------------------------
 
 ``MockNodeParameters`` and functions creating it no longer use a lambda expecting a ``NodeConfiguration`` object.
@@ -290,7 +327,7 @@ For instance, if you have 2 CorDapps containing the packages ``net.corda.example
 .. note:: If you have any CorDapp code (e.g. flows/contracts/states) that is only used by the tests and located in the same test module, it won't be discovered now.
     You will need to move them in the main module of one of your CorDapps or create a new, separate CorDapp for them, in case you don't want this code to live inside your production CorDapps.
 
-Step 7. Security: Add BelongsToContract annotations
+Step 8. Security: Add BelongsToContract annotations
 ---------------------------------------------------
 
 In versions of the platform prior to v4, it was the responsibility of contract and flow logic to ensure that ``TransactionState`` objects
@@ -307,7 +344,7 @@ to be governed by a contract that is either:
 Learn more by reading ":ref:`implicit_constraint_types`". If an app targets Corda 3 or lower (i.e. does not specify a target version),
 states that point to contracts outside their package will trigger a log warning but validation will proceed.
 
-Step 8. Learn about signature constraints and JAR signing
+Step 9. Learn about signature constraints and JAR signing
 ---------------------------------------------------------
 
 :doc:`design/data-model-upgrades/signature-constraints` are a new data model feature introduced in Corda 4. They make it much easier to
@@ -321,8 +358,8 @@ automatically use them if your application JAR is signed. **We recommend all JAR
 with developer certificates is deployed to a production node, the node will refuse to start. Therefore to deploy apps built for Corda 4
 to production you will need to generate signing keys and integrate them with the build process.
 
-Step 9. Security: Package namespace handling
+Step 10. Security: Package namespace handling
---------------------------------------------
+---------------------------------------------
 
 Almost no apps will be affected by these changes, but they're important to know about.
 
@@ -349,7 +386,7 @@ Whilst this feature is optional and not strictly required, it may be helpful to
 where type names may be taken "as read". You can learn more about this feature and the motivation for it by reading
 ":doc:`design/data-model-upgrades/package-namespace-ownership`".
 
-Step 10. Consider adding extension points to your flows
+Step 11. Consider adding extension points to your flows
 -------------------------------------------------------
 
 In Corda 4 it is possible for flows in one app to subclass and take over flows from another. This allows you to create generic, shared
@@ -359,7 +396,7 @@ into shared business logic, but it makes perfect sense to put into a user-specif
 
 If your flows could benefit from being extended in this way, read ":doc:`flow-overriding`" to learn more.
 
-Step 11. Possibly update vault state queries
+Step 12. Possibly update vault state queries
 --------------------------------------------
 
 In Corda 4 queries made on a node's vault can filter by the relevancy of those states to the node. As this functionality does not exist in
@@ -367,7 +404,7 @@ Corda 3, apps will continue to receive all states in any vault queries. However,
 to the node in question to query for only relevant states. See :doc:`api-vault-query.rst` for more details on how to do this. Not doing this
 may result in queries returning more states than expected if the node is using observer functionality (see ":doc:`tutorial-observer-nodes.rst`").
 
-Step 12. Explore other new features that may be useful
+Step 13. Explore other new features that may be useful
 ------------------------------------------------------
 
 Corda 4 adds several new APIs that help you build applications. Why not explore:

docs/source/cordapp-build-systems.rst

@@ -289,10 +289,9 @@ Also the best practice is to disable signing by the ``cordapp`` plugin as shown
 
 Example
 ^^^^^^^
-Below is a sample of what a CorDapp's Gradle dependencies block might look like. When building your own CorDapp, you
+Below is a sample CorDapp Gradle dependencies block. When building your own CorDapp, use the ``build.gradle`` file of the
-should base yourself on the ``build.gradle`` file of the
 `Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotlin>`_ or the
-`Java CorDapp Template <https://github.com/corda/cordapp-template-java>`_.
+`Java CorDapp Template <https://github.com/corda/cordapp-template-java>`_ as a starting point.
 
 .. container:: codeset
 
@@ -358,6 +357,8 @@ At start-up, nodes will load any CorDapps present in their ``cordapps`` folder.
 CorDapp JAR must be added to the ``<node_dir>/cordapps/`` folder (where ``node_dir`` is the folder in which the node's JAR 
 and configuration files are stored) and the node restarted.
 
+.. _cordapp_configuration_files_ref:
+
 CorDapp configuration files
 ---------------------------
 
@@ -367,11 +368,57 @@ name of the JAR of the CorDapp (eg; if your CorDapp is called ``hello-0.1.jar``
 Config files are currently only available in the `Typesafe/Lightbend <https://github.com/lightbend/config>`_ config format.
 These files are loaded when a CorDapp context is created and so can change during runtime.
 
-CorDapp configuration can be accessed from ``CordappContext::config`` whenever a ``CordappContext`` is available.
+CorDapp configuration can be accessed from ``CordappContext::config`` whenever a ``CordappContext`` is available. For example:
 
-There is an example project that demonstrates in ``samples`` called ``cordapp-configuration`` and API documentation in
+.. literalinclude:: ../../samples/cordapp-configuration/workflows/src/main/kotlin/net/corda/configsample/GetStringConfigFlow.kt
-`<api/kotlin/corda/net.corda.core.cordapp/index.html>`_.
+    :language: kotlin
+    :start-after: DOCSTART 1
+    :end-before: DOCEND 1
 
+Using CorDapp configuration with the deployNodes task
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If you want to generate CorDapp configuration when using the ``deployNodes`` Gradle task, then you can use the ``cordapp`` or ``projectCordapp``
+properties on the node. For example:
+
+.. sourcecode:: groovy
+
+    task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
+        nodeDefaults {
+            // this external CorDapp will be included in each project
+            cordapp("$corda_release_group:corda-finance-contracts:$corda_release_version")
+            // this external CorDapp will be included in each project with the given config
+            cordapp("$corda_release_group:corda-finance-workflows:$corda_release_version") {
+                config "issuableCurrencies = [ USD ]"
+            }
+        }
+        node {
+            name "O=Bank A,L=London,C=GB"c
+            ...
+            // This adds configuration for another CorDapp project within the build
+            cordapp (project(':my-project:workflow-cordapp')) {
+                config "someStringValue=test"
+            }
+            cordapp(project(':my-project:another-cordapp')) {
+                // Use a multiline string for complex configuration
+                config '''
+                    someStringValue=test
+                    anotherStringValue=10
+                 '''
+            }
+        }
+        node {
+            name "O=Bank B,L=New York,C=US"
+            ...
+            // This adds configuration for the default CorDapp for this project
+            projectCordapp {
+                config project.file("src/config.conf")
+            }
+        }
+    }
+
+There is an example project that demonstrates this in the ``samples`` folder of the Corda Git repository, called ``cordapp-configuration`` .
+API documentation can be found at `<api/kotlin/corda/net.corda.core.cordapp/index.html>`_.
 
 Minimum and target platform version
 -----------------------------------

samples/cordapp-configuration/workflows/src/main/kotlin/net/corda/configsample/GetStringConfigFlow.kt

@@ -11,6 +11,7 @@ import net.corda.core.serialization.CordaSerializable
 import net.corda.core.transactions.LedgerTransaction
 import net.corda.core.utilities.ProgressTracker
 
+// DOCSTART 1
 @StartableByRPC
 class GetStringConfigFlow(private val configKey: String) : FlowLogic<String>() {
     object READING : ProgressTracker.Step("Reading config")
@@ -23,3 +24,4 @@ class GetStringConfigFlow(private val configKey: String) : FlowLogic<String>() {
         return config.getString(configKey)
     }
 }
+// DOCEND 1