Docs: Setting up a HA notary (#1169)

Minor fixes: rename Notary -> notary, replica -> worker.

docs/source/running-a-notary-cluster/installing-percona.rst

@@ -54,7 +54,7 @@ Configuration
 Configure the MySQL Root Password (if necessary)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Some distros allow root access to the database through a Unix domain socket, others
+Some distributions allow root access to the database through a Unix domain socket, others
 require you to find the temporary password in the log file and change it upon
 first login.
 

docs/source/running-a-notary-cluster/installing-the-notary-service-netman.rst

@@ -8,27 +8,25 @@ Expected Outcome
 ~~~~~~~~~~~~~~~~
 
 You will go from a set of configuration files to a fully functional Corda network.
-The network map will be advertising the service identity of the Notary.  Every
-notary replica has obtained its own identity and the shared service identity
+The network map will be advertising the service identity of the notary. Every
+notary worker has obtained its own identity and the shared service identity
 from the doorman. 
 
-Using the registration tool, you will obtain the serivce identity of your notary
-cluster and distribute it to the keystores of all replicas of your notary
-cluster.
+Using the registration tool, you will obtain the service identity of your notary
+cluster and distribute it to the keystores of all worker nodes.
 
 The individual node identity is used by the messaging layer to route requests to
-individual notary replicas. The notary replicas sign using the service identity
-private key.
+specific workers. The workers sign transactions using the service identity private key.
 
-========  =========================== ===========================
-Host      Individual identity         Service identity
-========  =========================== ===========================
-notary-1  O=Replica 1, L=London, C=GB O=HA Notary, L=London, C=GB
-notary-2  O=Replica 2, L=London, C=GB O=HA Notary, L=London, C=GB
-notary-3  O=Replica 3, L=London, C=GB O=HA Notary, L=London, C=GB
-========  =========================== ===========================
+========  ========================== ===========================
+Host      Individual identity        Service identity
+========  ========================== ===========================
+notary-1  O=Worker 1, L=London, C=GB O=HA Notary, L=London, C=GB
+notary-2  O=Worker 2, L=London, C=GB O=HA Notary, L=London, C=GB
+notary-3  O=Worker 3, L=London, C=GB O=HA Notary, L=London, C=GB
+========  ========================== ===========================
 
-The notaries will be visible and available on the network. To list available notary
+The notary workers will be visible and available on the network. To list available notary
 identities using the Corda node shell
 
 .. code:: sh
@@ -43,7 +41,7 @@ CorDapp developers should select the notary service identity from the network ma
 
   serviceHub.networkMapCache.getNotary(CordaX500Name("HA Notary", "London", "GB"))
 
-Every notary replica's keystore contains the private key of the replica and the
+Every notary worker's keystore contains the private key of the replica and the
 private key of the notary service (with aliases ``identity-private-key`` and
 ``distributed-notary-private key`` in the keystore). We're going to create and
 populate the node's keystores later in this tutorial.
@@ -52,7 +50,7 @@ The Notary, the Doorman and the Network Map
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The notary is an essential component of every Corda network, therefore the
-Notary identity needs to be created first, before other nodes can join the
+notary identity needs to be created first, before other nodes can join the
 network, since the Notary identity is part of the network parameters.
 Adding a Corda notary to an existing network is covered in
 the network services documentation (TBD where this is hosted). Removing a notary from a network
@@ -76,9 +74,9 @@ Registering with the Doorman
 Obtaining the individual Node Identities
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Write the configuration files for your replicas as described in :doc:`installing-the-notary-service`.
+Write the configuration files for your notary nodes as described in :doc:`installing-the-notary-service`.
 
-Register all the notary replicas with the doorman using the ``--initial-registration``  flag.
+Register all the nodes with the doorman using the ``--initial-registration``  flag.
 
 .. code:: sh
 
@@ -91,7 +89,7 @@ Obtaining the distributed Service Identity
 
 Once you completed the initial registration for all notary nodes, you can use
 the registration tool to submit the certificate signing request (CSR) for the
-service identity of your notary cluster.  Read the documentation about the
+service identity of your notary cluster. Read the documentation about the
 `registration tool <https://github.com/corda/network-services/tree/master/registration-tool>`__
 for detailed instructions.
 

docs/source/running-a-notary-cluster/installing-the-notary-service.rst

@@ -4,7 +4,7 @@ Setting up the Notary Service
 
 In the previous section of this tutorial we set up a Percona cluster.
 
-On top of the Percona cluster we're deploying three Corda Enterprise Notary nodes ``notary-{1,2,3}`` and
+On top of the Percona cluster we're deploying three notary worker nodes ``notary-{1,2,3}`` and
 a single regular Corda node ``node-1`` that runs the notary health-check CorDapp.
 
 If you're deploying VMs in your environment you might need to adjust the host names accordingly.

docs/source/running-a-notary-cluster/introduction.rst

@@ -6,13 +6,13 @@ About the HA Notary Installation
 ================================
 
 In this chapter you'll learn how to set up, configure and start a highly
-available (HA) Corda Enterprise Notary from scratch. If you're targeting an
+available (HA) Corda Enterprise notary service from scratch. If you're targeting an
 environment with doorman and network map, you require the registration tool. If
 you don't require the doorman and network map, and you don't want to join an
 existing network, the bootstrapper allows you to set up a cluster of nodes from
 a set of configuration files.
 
-The HA Notary relies on a Percona/XtraDB (Percona) cluster. How to set up Percona
+The HA notary relies on a Percona/XtraDB (Percona) cluster. How to set up Percona
 is described below.
 
 This guide assumes you're running a Debian-based Linux OS.
@@ -26,23 +26,27 @@ Overview
 .. image:: resources/ha-notary-overview2.png
   :scale: 75 %
 
-The figure above displays the Corda nodes in green on the top, then the Corda
-notaries in red in the middle and on the bottom are the Percona nodes in blue.
+The figure above displays Corda client nodes in green on the top, then the Corda
+notary worker nodes in red in the middle and on the bottom are the Percona nodes in blue.
 
-Corda nodes that request a notarisation by the service name of the Notary,
-will connect to the available Notary nodes in a round-robin fashion.
+Client nodes that request a notarisation by the service name of the notary,
+will connect to the available worker nodes in a round-robin fashion.
 
-Since our Notary cluster consists of several Percona nodes and several Corda
-Notary nodes, we achieve high availability (HA). Individual nodes of the
-Percona and Notary clusters can fail, while clients are still able to
-notarise transactions. The Notary cluster remains available. A three-node
+The task of a worker node is to verify the notarisation request, the transaction timestamp (if present),
+and resolve and verify the transaction chain (if the notary service is validating). It then commits the
+transaction's input states to the Percona database.
+
+Since our notary cluster consists of several Percona nodes and several
+worker nodes, we achieve high availability (HA). Individual nodes of the
+Percona and notary clusters can fail, while clients are still able to
+notarise transactions. The notary cluster remains available. A three-node
 Percona cluster as shown in the figure above can tolerate one crash fault.
 
 .. note::
 
   In production you should consider running five nodes or more, to be able to
-  tolerate more than one simultaneous crash fault. One single Corda Notary
-  replica is enough to serve traffic in principal, although its capacity might
+  tolerate more than one simultaneous crash fault. One single Corda notary
+  worker is enough to serve traffic in principle, although its capacity might
   not be sufficient, depending on your throughput and latency requirements.
 
 Colocating Percona and the Notary Service
@@ -51,34 +55,34 @@ Colocating Percona and the Notary Service
 .. image:: resources/percona-colocated.png
   :scale: 50%
 
-You can run a Percona DB service and a Corda Notary service on the same machine.
+You can run a Percona Server and a Corda notary worker on the same machine.
 
 Summary
 +++++++
 
-* Corda nodes communicate with the Notary cluster via P2P messaging, the messaging layer handles selecting an appropriate Notary replica by the service legal name.
-* Corda nodes connect to the Notary cluster members round-robin.
-* The notaries communicate with the underlying Percona cluster via JDBC.
+* Client nodes communicate with the notary cluster via P2P messaging, the messaging layer handles selecting an appropriate notary worker node by the service legal name.
+* Client nodes connect to the notary cluster members round-robin.
+* The notary worker nodes communicate with the underlying Percona cluster via JDBC.
 * The Percona nodes communicate with each other via group communication (GComm).
-* The Percona replicas should only be reachable from each other and from the Notary nodes.
-* The Notary P2P ports should be reachable from the internet (or at least from the rest of the Corda network you're building or joining).
-* We recommend running the notaries and the Percona service in a joined private subnet, opening up the P2P ports of the notaries for external traffic.
+* The Percona replicas should only be reachable from each other and from the worker nodes.
+* The worker P2P ports should be reachable from the internet (or at least from the rest of the Corda network you're building or joining).
+* We recommend running the worker nodes and the Percona service in a joined private subnet, opening up the P2P ports of the workers for external traffic.
 
 Legal Names and Identities
 ++++++++++++++++++++++++++
 
-Every Notary replica has two legal names. Its own legal name, specified by
-``myLegalName``, e.g ``O=Replica 1, C=GB, L=London`` and the service legal name
+Every notary worker node has two legal names. Its own legal name, specified by
+``myLegalName``, e.g ``O=Worker 1, C=GB, L=London`` and the service legal name
 specified in configuration by ``notary.serviceLegalName``, e.g. ``O=HA Notary,
 C=GB, L=London``. Only the service legal name is included in the network
-parameters. CorDapp developers should select the Notary service identity from the network map cache.
+parameters. CorDapp developers should select the notary service identity from the network map cache.
 
 .. code:: kotlin
 
   serviceHub.networkMapCache.getNotary(CordaX500Name("HA Notary", "London", "GB"))
 
-Every Notary replica's keystore contains the private key of the replica and the
-private key of the Notary service (with aliases ``identity-private-key`` and
+Every notary worker's keystore contains the private key of the worker and the
+private key of the notary service (with aliases ``identity-private-key`` and
 ``distributed-notary-private key`` in the keystore). We're going to create and
 populate the node's keystores later in this tutorial.
 
@@ -96,7 +100,7 @@ Choosing Installation Path
 Expected Data Volume
 ====================
 
-For non-validating notaries the Notary stores roughly one kilobyte per transaction.
+For non-validating notaries the notary stores roughly one kilobyte per transaction.
 
 Prerequisites
 =============
@@ -108,7 +112,7 @@ Prerequisites
 * Network Registration tool (only required when setting up a network with doorman and network map)
 * Root access to a Linux machine or VM to install Percona
 * The private IP addresses of your DB hosts (where we're going to install Percona)
-* The public IP addresses of your Notary hosts (in order to advertise these IPs for P2P traffic)
+* The public IP addresses of your notary hosts (in order to advertise these IPs for P2P traffic)
 
 Your Corda distribution should contain all the JARs listed above.
 
@@ -126,7 +130,7 @@ keep them safe.
 Password or Keystore             Description
 ================================ ============================================================================================================
 database root password           used to create the Corda user, setting up the DB and tables (only required for some installation methods)
-Corda DB user password           used by the Notary service to access the DB
+Corda DB user password           used by the notary service to access the DB
 SST DB user password             used by the Percona cluster for data replication (SST stands for state snapshot transfer)
 Network root truststore password (not required when using the bootstrapper)
 Node keystore password           (not required when using the bootstrapper)
@@ -141,7 +145,7 @@ Percona Cluster
 =====  =======================
 Port   Purpose
 =====  =======================
-3306   MySQL client connections (from the Corda Notary nodes)
+3306   MySQL client connections (from the Corda notary nodes)
 4444   SST via rsync and Percona XtraBackup
 4567   Write-set replication traffic (over TCP) and multicast replication (over TCP and UDP)
 4568   IST (Incremental State Transfer)
@@ -160,7 +164,7 @@ P2P Port   10002   P2P traffic (external)
 RPC Port   10003   RPC traffic (internal only)
 =========  ======= ==============================
 
-Later in the tutorial we're covering the Notary service configuration in details, in :doc:`installing-the-notary-service`.
+Later in the tutorial we're covering the notary service configuration in details, in :doc:`installing-the-notary-service`.
 
 Keys and Certificates
 +++++++++++++++++++++

docs/source/running-a-notary-cluster/resources/node.conf

@@ -24,7 +24,7 @@ trustStorePassword = ""
 p2pAddress : "{{ fully qualified domain name, e.g. host.example.com (or localhost in development) }}:{{ P2P port }}"
 
 rpcUsers=[]
-myLegalName : "O=Replica 1, C=GB, L=London"
+myLegalName : "O=Worker 1, C=GB, L=London"
 
 // We recommend using Postgres for the node database, or an other supported
 // database that you already have set up. Note that the notarised states