Docs: introduce a page about upgrading the node.

docs/source/index.rst

@@ -33,6 +33,7 @@ We look forward to seeing what you can do with Corda!
 
    release-notes
    app-upgrade-notes
+   node-upgrade-notes
 
 .. toctree::
    :caption: Development

docs/source/key-concepts-node.rst

@@ -81,11 +81,13 @@ The node also has several CorDapps installed by default to handle common tasks s
 * Upgrading contracts
 * Broadcasting agreed ledger updates for recording by counterparties
 
+.. _draining-mode:
+
 Draining mode
-^^^^^^^^^^^^^
+-------------
 
 In order to operate a clean shutdown of a node, it is important than no flows are in-flight, meaning no checkpoints should
-be persisted. The node is able to be put in a Flows Draining Mode, during which:
+be persisted. The node is able to be put in draining mode, during which:
 
 * Commands requiring to start new flows through RPC will be rejected.
 * Scheduled flows due will be ignored.
@@ -94,3 +96,5 @@ be persisted. The node is able to be put in a Flows Draining Mode, during which:
 
 As their number - which can be monitored through RPC - reaches zero, it is safe to shut the node down.
 This property is durable, meaning that restarting the node will not reset it to its default value and that a RPC command is required.
+
+The node can be safely shut down via a drain using the shell.

docs/source/node-administration.rst

@@ -128,7 +128,7 @@ due to expensive run-time costs. They can be turned on and off explicitly regard
 When starting Corda nodes using Cordformation runner (see :doc:`running-a-node`), you should see a startup message similar to the following:
 **Jolokia: Agent started with URL http://127.0.0.1:7005/jolokia/**
 
-When starting Corda nodes using the `DriverDSL`, you should see a startup message in the logs similar to the following:
+When starting Corda nodes using the 'driver DSL', you should see a startup message in the logs similar to the following:
 **Starting out-of-process Node USA Bank Corp, debug port is not enabled, jolokia monitoring port is 7005 {}**
 
 
@@ -203,6 +203,8 @@ For launching on Windows without PowerShell, it is not possible to perform comma
 .. warning:: If this approach is taken, the passwords will appear in the windows command prompt history.
 
 
+.. _ref-backup-recommendations:
+
 Backup recommendations
 ----------------------
 

docs/source/node-upgrade-notes.rst

@@ -0,0 +1,63 @@
+Upgrading your node to Corda 4
+==============================
+
+Corda releases strive to be backwards compatible, so upgrading a node is fairly straightforward and should not require changes to
+applications. It consists of the following steps:
+
+1. Drain the node.
+2. Make a backup of your node directories and/or database.
+3. Replace the ``corda.jar`` file with the new version.
+4. Start up the node. This step may incur a delay whilst any needed database migrations are applied.
+5. Undrain it to re-enable processing of new inbound flows.
+
+The protocol is designed to tolerate node outages, so during the upgrade process peers on the network will wait for your node to come back.
+
+Step 1. Drain the node
+----------------------
+
+Before a node or application on it can be upgraded, the node must be put in :ref:`draining-mode`. This brings the currently running
+:doc:`key-concepts-flows` to a smooth halt such that existing work is finished and new work is queuing up rather than being processed.
+
+Draining flows is a key task for node administrators to perform. It exists to simplify applications by ensuring apps don't have to be
+able to migrate workflows from any arbitrary point to other arbitrary points, a task that would rapidly become infeasible as workflow
+and protocol complexity increases.
+
+To drain the node, run the ``gracefulShutdown`` command. This will wait for the node to drain and then shut down the node when the drain
+is complete.
+
+.. warning:: The length of time a node takes to drain depends on both how your applications are designed, and whether any apps are currently
+   talking to network peers that are offline or slow to respond. It is thus hard to give guidance on how long a drain should take, but in
+   an environment with well written apps and in which your counterparties are online, drains may need only a few seconds.
+
+Step 2. Make a backup of your node directories and/or database
+--------------------------------------------------------------
+
+It's always a good idea to make a backup of your data before upgrading any server. This will make it easy to roll back if there's a problem.
+You can simply make a copy of the node's data directory to enable this. If you use an external non-H2 database please consult your database
+user guide to learn how to make backups.
+
+We provide some `backup recommendations <backup-recommendations>`_ if you'd like more detail.
+
+Step 3. Replace ``corda.jar`` with the new version
+--------------------------------------------------
+
+Download the latest version of Corda from `our Artifactory site <https://ci-artifactory.corda.r3cev.com/artifactory/webapp/#/artifacts/browse/simple/General/corda/net/corda/corda-node>`_.
+Make sure it's available on your path, and that you've read the :doc:`release-notes`, in particular to discover what version of Java this
+node requires.
+
+.. important:: Corda 4 requires Java |java_version| or any higher Java 8 patchlevel. Java 9+ is not currently supported.
+
+Step 4. Start up the node
+-------------------------
+
+Start the node in the usual manner you have selected. The node will perform any automatic data migrations required, which may take some
+time. If the migration process is interrupted it can be continued simply by starting the node again, without harm.
+
+Step 5. Undrain the node
+------------------------
+
+You may now do any checks that you wish to perform, read the logs, and so on. When you are ready, use this command at the shell:
+
+``run setFlowsDrainingModeEnabled enabled: false``
+
+Your upgrade is complete.