CORDA-2301 JVM args documentation (#4417)

* Document the ways and behaviours of setting JVM args on a corda node process.

* Small review fixes

* Clarification, removing outdated jvmArgs documentation

docs/source/corda-configuration-file.rst

@@ -204,9 +204,6 @@ The available config fields are listed below.
 
         .. note:: This is an unsupported configuration.
 
-:jvmArgs: An optional list of JVM args, as strings, which replace those inherited from the command line when launching via ``corda.jar``
-    only. e.g. ``jvmArgs = [ "-Xmx220m", "-Xms220m", "-XX:+UseG1GC" ]``
-
 :systemProperties: An optional map of additional system properties to be set when launching via ``corda.jar`` only.  Keys and values
     of the map should be strings. e.g. ``systemProperties = { visualvm.display.name = FooBar }``
 
@@ -272,6 +269,12 @@ The available config fields are listed below.
     :excludedAutoAcceptableParameters: List of auto-acceptable parameter names to explicitly exclude from auto-accepting. Allows a node operator to control the behaviour at a
                                        more granular level. Defaults to an empty list.
 
+:custom: Set custom command line attributes (e.g. Java system properties) on the node process via the capsule launcher
+
+        :jvmArgs: A list of JVM arguments to apply to the node process. This removes any defaults specified from ``corda.jar``, but can be
+                  overriden from the command line. See :ref:`setting_jvm_args` for examples and details on the precedence of the different
+                  approaches to settings arguments.
+
 Examples
 --------
 

docs/source/deploying-a-node.rst

@@ -56,6 +56,7 @@ handling, and ensures the Corda service is run at boot.
               ]
           }
       ]
+      custom { jvmArgs = [ '-Xmx2048m', '-XX:+UseG1GC' ] }
 
 7. Make the following changes to ``/opt/corda/node.conf``:
 
@@ -90,7 +91,7 @@ handling, and ensures the Corda service is run at boot.
        Type=simple
        User=corda
        WorkingDirectory=/opt/corda
-       ExecStart=/usr/bin/java -Xmx2048m -jar /opt/corda/corda.jar
+       ExecStart=/usr/bin/java -jar /opt/corda/corda.jar
        Restart=on-failure
 
        [Install]
@@ -108,14 +109,15 @@ handling, and ensures the Corda service is run at boot.
         respawn
         setuid corda
         chdir /opt/corda
-        exec java -Xmx2048m -jar /opt/corda/corda.jar
+        exec java -jar /opt/corda/corda.jar
 
 9. Make the following changes to ``corda.service`` or ``corda.conf``:
 
     * Make sure the service description is informative - particularly if you plan to run multiple nodes.
     * Change the username to the user account you want to use to run Corda. **We recommend that this user account is
       not root**
-    * Set the maximum amount of memory available to the Corda process by changing the ``-Xmx2048m`` parameter
+    * Set the maximum amount of memory available to the Corda process by changing the ``-Xmx2048m`` parameter in
+      the config file
     * **SystemD**: Make sure the ``corda.service`` file is owned by root with the correct permissions:
 
         * ``sudo chown root:root /etc/systemd/system/corda.service``

docs/source/running-a-node.rst

@@ -43,6 +43,41 @@ Optionally run the node's webserver as well by opening a terminal window in the
 
 .. warning:: The node webserver is for testing purposes only and will be removed soon.
 
+.. _setting_jvm_args:
+
+Setting JVM arguments
+~~~~~~~~~~~~~~~~~~~~~
+
+There are several ways of setting JVM arguments for the node process (particularly the garbage collector and the memory settings).
+They are listed here in order of increasing priority, i.e. if the same flag is set in a way later in this list, it will override
+anything set earlier.
+
+:Default arguments in capsule: The capsuled corda node has default flags set to ``-Xmx512m -XX:+UseG1GC`` - this gives the node (a relatively
+   low) 512 MB of heap space and turns on the G1 garbage collector, ensuring low pause times for garbage collection.
+
+:Node configuration: The node configuration file can specify custom default JVM arguments by adding a section like::
+
+      custom = {
+         jvmArgs: [ '-Xmx1G', '-XX:+UseG1GC' ]
+      }
+
+   Note that this will completely replace any defaults set by capsule above, not just the flags that are set here, so if you use this
+   to set e.g. the memory, you also need to set the garbage collector, or it will revert to whatever default your JVM is using.
+
+:Capsule specific system property: You can use a special system property that Capsule understands to set JVM arguments only for the Corda
+   process, not the launcher that actually starts it::
+
+      java -Dcapsule.jvm.args="-Xmx:1G" corda.jar
+
+   Setting a property like this will override any value for this property, but not interfere with any other JVM arguments that are configured
+   in any way mentioned above. In this example, it would reset the maximum heap memory to ``-Xmx1G`` but not touch the garbage collector settings.
+   This is particarly useful for either setting large memory allowances that you don't want to give to the launcher or for setting values that
+   can only be set on one process at a time, e.g. a debug port.
+
+:Command line flag: You can set JVM args on the command line that apply to the launcher process and the node process as in the example
+      above. This will override any value for the same flag set any other way, but will leave any other JVM arguments alone.
+
+
 Command-line options
 ~~~~~~~~~~~~~~~~~~~~
 The node can optionally be started with the following command-line options: