CORDA-1048 - Making it simpler to move an existing local deployment of nodes to across different machines (#2697)

* Various cleanup of the network map code (#2604)

(cherry picked from commit 2af0fee)

* CORDA-1048: Making it simpler to move an existing local deployment of nodes to across different machines. (#2672)

This was achieved by having the hash in the node-info file to be just of the node's X.500 name. This also solves existing duplicate node-info file issues that we've been having.

Also updated the docsite.

(cherry picked from commit 8616f24)

docs/source/corda-configuration-file.rst

@@ -88,7 +88,7 @@ path to the node's base directory.
 :p2pAddress: The host and port on which the node is available for protocol operations over ArtemisMQ.
 
     .. note:: In practice the ArtemisMQ messaging services bind to all local addresses on the specified port. However,
-        note that the host is the included as the advertised entry in the NetworkMapService. As a result the value listed
+        note that the host is the included as the advertised entry in the network map. As a result the value listed
         here must be externally accessible when running nodes across a cluster of machines. If the provided host is unreachable,
         the node will try to auto-discover its public one.
 

docs/source/generating-a-node.rst

@@ -1,8 +1,6 @@
 Creating nodes locally
 ======================
 
-.. contents::
-
 Node structure
 --------------
 Each Corda node has the following structure:
@@ -70,8 +68,8 @@ The name must also obey the following constraints:
 The Cordform task
 -----------------
 Corda provides a gradle plugin called ``Cordform`` that allows you to automatically generate and configure a set of
-nodes. Here is an example ``Cordform`` task called ``deployNodes`` that creates three nodes, defined in the
-`Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotlin/blob/release-V3/build.gradle#L100>`_:
+nodes for testing and demos. Here is an example ``Cordform`` task called ``deployNodes`` that creates three nodes, defined
+in the `Kotlin CorDapp Template <https://github.com/corda/cordapp-template-kotlin/blob/release-V3/build.gradle#L100>`_:
 
 .. sourcecode:: groovy
 
@@ -165,8 +163,7 @@ a single node to run the network map service, by putting its name in the ``netwo
 .. warning:: When adding nodes, make sure that there are no port clashes!
 
 The Dockerform task
--------------------
-
+~~~~~~~~~~~~~~~~~~~
 The ```Dockerform``` is a sister task of ```Cordform```. It has nearly the same syntax and produces very
 similar results - enhanced by an extra file to enable easy spin up of nodes using ```docker-compose```.
 Below you can find the example task from the ```IRS Demo<https://github.com/corda/corda/blob/release-V3.0/samples/irs-demo/cordapp/build.gradle#L111>```
@@ -230,7 +227,7 @@ by default exposes port 10003 which is the default one for RPC connections.
 
 
 Running deployNodes
--------------------
+~~~~~~~~~~~~~~~~~~~
 To create the nodes defined in our ``deployNodes`` task, run the following command in a terminal window from the root
 of the project where the ``deployNodes`` task is defined:
 

docs/source/hello-world-running.rst

@@ -21,7 +21,7 @@ service.
     task deployNodes(type: net.corda.plugins.Cordform, dependsOn: ['jar']) {
         directory "./build/nodes"
         node {
-            name "O=NetworkMapAndNotary,L=London,C=GB"
+            name "O=Notary,L=London,C=GB"
             notary = [validating : true]
             p2pPort 10002
             rpcPort 10003
@@ -142,7 +142,7 @@ The vaults of PartyA and PartyB should both display the following output:
           - "C=GB,L=London,O=PartyA"
           - "C=US,L=New York,O=PartyB"
         contract: "com.template.contract.IOUContract"
-        notary: "C=GB,L=London,O=NetworkMapAndNotary,CN=corda.notary.validating"
+        notary: "C=GB,L=London,O=Notary"
         encumbrance: null
         constraint:
           attachmentId: "F578320232CAB87BB1E919F3E5DB9D81B7346F9D7EA6D9155DC0F7BA8E472552"
@@ -157,7 +157,7 @@ The vaults of PartyA and PartyB should both display the following output:
       recordedTime: 1506415268.875000000
       consumedTime: null
       status: "UNCONSUMED"
-      notary: "C=GB,L=London,O=NetworkMapAndNotary,CN=corda.notary.validating"
+      notary: "C=GB,L=London,O=Notary"
       lockId: null
       lockUpdateTime: 1506415269.548000000
     totalStatesAvailable: -1

docs/source/setting-up-a-corda-network.rst

@@ -57,9 +57,9 @@ in its local network map cache. The node generates its own node-info file on sta
 In addition to the network map, all the nodes on a network must use the same set of network parameters. These are a set
 of constants which guarantee interoperability between nodes. The HTTP network map distributes the network parameters
 which the node downloads automatically. In the absence of this the network parameters must be generated locally. This can
-be done with the network bootstrapper. This a tool that scans all the node configurations from a common directory to
+be done with the network bootstrapper. This is a tool that scans all the node configurations from a common directory to
 generate the network parameters file which is copied to the nodes' directories. It also copies each node's node-info file
-to every other node.
+to every other node so that they can all transact with each other.
 
 The bootstrapper tool can be built with the command:
 
@@ -82,6 +82,12 @@ For example running the command on a directory containing these files :
 
 Would generate directories containing three nodes: notary, partya and partyb.
 
+This tool only bootstraps a network. It cannot dynamically update if a new node needs to join the network or if an existing
+one has changed something in their node-info, e.g. their P2P address. For this the new node-info file will need to be placed
+in the other nodes' ``additional-node-infos`` directory. A simple way to do this is to use `rsync <https://en.wikipedia.org/wiki/Rsync>`_.
+However, if it's known beforehand the set of nodes that will eventually the node folders can be pregenerated in the bootstrap
+and only started when needed.
+
 Starting the nodes
 ~~~~~~~~~~~~~~~~~~
 

docs/source/tutorial-cordapp.rst

@@ -17,7 +17,7 @@ if:
 
 We will deploy the CorDapp on 4 test nodes:
 
-* **NetworkMapAndNotary**, which hosts a validating notary service
+* **Notary**, which hosts a validating notary service
 * **PartyA**
 * **PartyB**
 * **PartyC**
@@ -252,7 +252,7 @@ For each node, the ``runnodes`` script creates a node tab/window:
 
     Fri Jul 07 10:33:47 BST 2017>>>
 
-For every node except the network map/notary, the script also creates a webserver terminal tab/window:
+For every node except the notary, the script also creates a webserver terminal tab/window:
 
 .. sourcecode:: none
 
@@ -471,23 +471,27 @@ For more information on the client RPC interface and how to build an RPC client
 
 Running Nodes Across Machines
 -----------------------------
-The nodes can be split across machines and configured to communicate across the network.
+The nodes can be split across different machines and configured to communicate across the network.
 
-After deploying the nodes, navigate to the build folder (``kotlin-source/build/nodes``) and move some of the individual
-node folders to a different machine (e.g. using a USB key). It is important that none of the nodes - including the
-network map/notary node - end up on more than one machine. Each computer should also have a copy of ``runnodes`` and
-``runnodes.bat``.
+After deploying the nodes, navigate to the build folder (``kotlin-source/build/nodes``) and for each node that needs to
+be moved to another machine open its config file and change the Artemis messaging address to the IP address of the machine
+where the node will run (e.g. ``p2pAddress="10.18.0.166:10006"``).
+
+These changes require new node-info files to be distributed amongst the nodes. Use the network bootstrapper tool
+(see :doc:`setting-up-a-corda-network` for more information on this and how to built it) to update the files and have
+them distributed locally.
+
+``java -jar network-bootstrapper.jar kotlin-source/build/nodes``
+
+Once that's done move the node folders to their designated machines (e.g. using a USB key). It is important that none of the
+nodes - including the notary - end up on more than one machine. Each computer should also have a copy of ``runnodes``
+and ``runnodes.bat``.
 
 For example, you may end up with the following layout:
 
-* Machine 1: ``NetworkMapAndNotary``, ``PartyA``, ``runnodes``, ``runnodes.bat``
+* Machine 1: ``Notary``, ``PartyA``, ``runnodes``, ``runnodes.bat``
 * Machine 2: ``PartyB``, ``PartyC``, ``runnodes``, ``runnodes.bat``
 
-You must now edit the configuration file for each node, including the network map/notary. Open each node's config file,
-and make the following changes:
-
-* Change the Artemis messaging address to the machine's IP address (e.g. ``p2pAddress="10.18.0.166:10006"``)
-
 After starting each node, the nodes will be able to see one another and agree IOUs among themselves.
 
 Debugging your CorDapp