CORDA-1912: Add documentation on the options for deploying nodes (#5183)

docs/source/corda-configuration-file.rst

@@ -168,6 +168,8 @@ detectPublicIp
 
   *Default:* false
 
+.. _corda_configuration_file_dev_mode:
+
 devMode
   This flag sets the node to run in development mode.
   On startup, if the keystore ``<workspace>/certificates/sslkeystore.jks``
@@ -241,6 +243,8 @@ h2Port (deprecated)
 
   **Important: Deprecated please use h2Setting instead**
 
+.. _corda_configuration_file_h2_settings:
+
 h2Settings
   Sets the H2 JDBC server host and port.
   See :doc:`node-database-access-h2`.
@@ -304,6 +308,8 @@ messagingServerExternal
 
   *Default:* not defined
 
+.. _corda_configuration_file_myLegalName:
+
 myLegalName
   The legal identity of the node.
   This acts as a human-readable alias to the node's public key and can be used with the network map to look up the node's info.
@@ -313,6 +319,8 @@ myLegalName
 
   *Default:* not defined
 
+.. _corda_configuration_file_notary:
+
 notary
   Optional configuration object which if present configures the node to run as a notary. If part of a Raft or BFT-SMaRt
   cluster then specify ``raft`` or ``bftSMaRt`` respectively as described below. If a single node notary then omit both.
@@ -420,6 +428,8 @@ rpcAddress (deprecated)
 
   *Default:* not defined
 
+.. _corda_configuration_file_rpc_settings:
+
 rpcSettings
   Options for the RPC server exposed by the Node.
 
@@ -458,6 +468,8 @@ rpcSettings
 
         *Default:* not defined
 
+.. _corda_configuration_file_rpc_users:
+
 rpcUsers
   A list of users who are authorised to access the RPC system.
   Each user in the list is a configuration object with the following fields:
@@ -484,6 +496,8 @@ security
   Contains various nested fields controlling user authentication/authorization, in particular for RPC accesses.
   See :doc:`clientrpc` for details.
 
+.. _corda_configuration_file_sshd:
+
 sshd
   If provided, node will start internal SSH server which will provide a management shell.
   It uses the same credentials and permissions as RPC subsystem.

docs/source/generating-a-node.rst

@@ -106,10 +106,120 @@ Additionally, all three nodes will include any CorDapps defined in the project's
 CorDapps are not listed in each node's ``cordapps`` entry. This means that running the ``deployNodes`` task from the
 template CorDapp, for example, would automatically build and add the template CorDapp to each node.
 
-You can extend ``deployNodes`` to generate additional nodes.
+The configuration values available in ``deployNodes`` task are as follows:
+
+Required configuration
+^^^^^^^^^^^^^^^^^^^^^^
+
+* ``name`` <string>
+
+  * The legal identity name of the Corda node. (see :ref:`myLegalName <corda_configuration_file_myLegalName>`)
+  * e.g.
+    ::
+
+        name "O=PartyA,L=London,C=GB"
+
+* ``p2pAddress`` <string> <**required if p2pPort not specified**>
+
+  * The address/port the node uses for inbound communication from other nodes. (see :ref:`p2pAddress <corda_configuration_file_p2pAddress>`)
+  * e.g.
+    ::
+
+        p2pAddress "example.com:10002"
+
+* ``p2pPort`` <integer>
+
+  * The port the node uses for inbound communication from other nodes.  Assumes the address is ``localhost``. (see :ref:`p2pAddress <corda_configuration_file_p2pAddress>`)
+  * e.g.
+    ::
+
+        p2pPort 10006  // "localhost:10006"
+
+* ``rpcSettings`` <config>
+
+  * Specifies RPC settings for the node. (see :ref:`rpcSettings <corda_configuration_file_rpc_settings>`)
+  * e.g.
+    ::
+
+        rpcSettings {
+          port 10006
+          adminPort 10026
+        }
+
+Optional configuration
+^^^^^^^^^^^^^^^^^^^^^^
+
+* ``notary`` <config> (see :ref:`notary <corda_configuration_file_notary>`)
+
+  * Optional configuration which specifies the node is a notary.
+  * .. note:: <**required**> for notary nodes
+
+* ``devMode`` <boolean>
+
+  * When true enables development mode. (see :ref:`devMode <corda_configuration_file_dev_mode>`)
+  * e.g.
+    ::
+
+        devMode true
+
+* ``webAddress`` <string>
+
+  * Configure a webserver to connect to the node via RPC. This will specify the address and port it will listen on. The node must have an RPC address configured. (see :ref:`Specifying a custom webserver<specify-custom-webserver>`)
+  * e.g.
+    ::
+
+        webAddress  "example.com:10011"
+
+* ``webPort`` <integer>
+
+  * Configure a webserver to connect to the node via RPC. Defaults the address to `localhost`. The node must have an RPC address configured. (see :ref:`Specifying a custom webserver<specify-custom-webserver>`)
+  * e.g.
+    ::
+
+        webPort  10011  // "localhost:10011"
+
+* ``rpcUsers`` <list>
+
+  * Set the RPC users for this node. (see :ref:`rpcUsers <corda_configuration_file_rpc_users>`)
+  * e.g.
+    ::
+
+        rpcUsers = [[ user: "user1", "password": "test", "permissions": ["StartFlow.net.corda.flows.MyFlow"]]]
+
+  * This configuration block allows arbitrary configuration. Incorrect configurations will not cause a DSL error.
+
+* ``configFile`` <string>
+
+  * For extending configuration of nodes. (see :ref:`extended node configuration <generating_a_node_extended_config>`)
+  * e.g.
+    ::
+
+        configFile = "samples/trader-demo/src/main/resources/node-b.conf"
+
+* ``https`` <boolean>
+
+  * When true enables HTTPS communication from the node webserver.
+  * e.g.
+    ::
+
+        https true
+
+* ``sshdPort`` <integer>
+
+  * Specifies the port for sshd communication. (see :ref:`sshd <corda_configuration_file_sshd>`)
+  * e.g.
+    ::
+
+        sshd {
+          port = 2222
+        }
+
+You can extend the task ``deployNodes`` with more ``node {}`` blocks to generate as many nodes as necessary for your application.
 
 .. warning:: When adding nodes, make sure that there are no port clashes!
 
+.. _generating_a_node_extended_config:
+
 To extend node configuration beyond the properties defined in the ``deployNodes`` task use the ``configFile`` property with the path (relative or absolute) set to an additional configuration file.
 This file should follow the standard :doc:`corda-configuration-file` format, as per node.conf. The properties from this file will be appended to the generated node configuration. Note, if you add a property already created by the 'deployNodes' task, both properties will be present in the file.
 The path to the file can also be added while running the Gradle task via the ``-PconfigFile`` command line option. However, the same file will be applied to all nodes.
@@ -232,6 +342,8 @@ The snippet below configures contracts classes from Finance CorDapp to be verifi
         includeWhitelist = [ "net.corda.finance.contracts.asset.Cash", "net.corda.finance.contracts.asset.CommercialPaper" ]
         //...
 
+.. _specify-custom-webserver:
+
 Specifying a custom webserver
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 By default, any node listing a web port will use the default development webserver, which is not production-ready. You