Install Target and Platform Update (#534)

* Install Target and Platform Update
* Rewrite platform configs
* Update installation section
* DM Review Feedback
* Further changes to platform examples
* Response to review
Co-authored-by: Tim Pillinger <[email protected]>

Author: datamel

src/7-to-8/caveats.rst

@@ -58,7 +58,7 @@ Multiple Selection
    * https://github.com/cylc/cylc-ui/issues/434
 Installing Workflows
    At present there is no way to view or install
-   :term:`source workflows <source directory>`) in the UI.
+   :term:`source workflows <source directory>` in the UI.
 Rose Edit
    Rose Edit is awaiting reimplementation in the UI.
 Trigger Edit

src/7-to-8/major-changes/cylc-install.rst

@@ -89,7 +89,7 @@ Remote Installation
 
 Remote file installation does not occur until running the workflow.
 When the first task runs on a remote platform, Cylc will transfer files from
-the :term:`run directory` to the install target.
+the :term:`run directory` to the :term:`install target`.
 
 If you have used Rose 2019, you may be used to all files and directories in
 the run directory being included.

src/7-to-8/major-changes/platforms.rst

@@ -31,8 +31,9 @@ In Cylc 8 "platforms" can be defined in the global configuration
 (:cylc:conf:`global.cylc`) so that this configuration doesn't have to be
 repeated for each task in each workflow.
 
-Cylc "platforms" may configure hostnames, job runners and more. Only the
-platform name needs to be specified in the task configuration.
+There may be cases where sets of platforms (for example a group of
+standalone compute servers, or a pair of mirrored HPC's) might be equally
+suitable for a task. Such platforms can be set up to be ``platform groups``
 
 .. seealso::
 
@@ -167,7 +168,7 @@ At Cylc 8 the equivalent might be:
 
        [[mytask_login_to_hpc_and_submit]]
            # Recommended:
-           platform = just_run_it
+           platform = slurm_supercomputer
            # ...but This is still legal:
            #platform = $(selector-script)
 
@@ -183,13 +184,25 @@ And the platform settings for these examples might be:
            # A computer with PBS, that takes local job submissions
            job runner = pbs
            hosts = localhost
+           install target = localhost
 
        [[slurm_supercomputer]]
            # This computer with Slurm requires you to use a login node.
            hosts = login_node01, login_node02  # Cylc will pick a host.
            job runner = slurm
 
 
+Note that in these examples, it is assumed that ``linuxboxNN``, ``pbs_local`` and
+``slurm_supercomputer`` have distinct file systems.
+Sets of platforms which share a file system must specify
+a single :ref:`install target <Install Targets>`.
+
+.. note::
+   If an install target is not set, a platform will use its own platform name
+   as the install target name. If multiple platforms share a file system
+   but have separate :ref:`install targets <Install Targets>` task initialization
+   will fail.
+
 .. _host-to-platform-logic:
 
 How Cylc 8 handles host-to-platform upgrades
@@ -216,6 +229,7 @@ platforms section:
        [[supercomputer_A]]
            hosts = localhost
            job runner = slurm
+           install target = localhost
        [[supercomputer_B]]
            hosts = tigger, wol, eeyore
            job runner = pbs
@@ -230,7 +244,7 @@ And you have a workflow runtime configuration:
                batch system = slurm
        [[task2]]
            [[[remote]]]
-               hosts = eeyore
+               host = eeyore
            [[[job]]]
                batch system = pbs
 

src/glossary.rst

@@ -1051,6 +1051,14 @@ Glossary
 
          * :term:`reinstall`
 
+   install target
+      Cylc uses install targets to determine which platforms share file systems.
+      Install targets should normally be managed at site level. They are configured in
+      :cylc:conf:`global.cylc[platforms][<platform name>]install target`.
+
+      .. seealso::
+
+         * :ref:`Install Targets`
 
    reinstall
    reinstallation

src/installation.rst

@@ -237,12 +237,13 @@ To do so create a symbolic link to the wrapper, for each of these commands:
 Configuration
 -------------
 
-Cylc uses "sane and safe" defaults and is suitable for use "out of the box".
+Cylc uses sane and safe defaults and is suitable for use "out of the box",
+if all you need to do is run jobs locally in the background.
 However, many things may need to be configured, e.g:
 
-* Job hosts
-* Communication methods
-* User/Site preferences
+* :ref:`AdminGuide.PlatformConfigs` (jobs hosts, runners, etc)
+* :ref:`Scheduler Hosts<Submitting Workflows To a Pool Of Hosts>`
+* :ref:`Default Event Handlers<EventHandlers>`
 
 Cylc Flow
 ^^^^^^^^^
@@ -255,6 +256,20 @@ configuration of the system on both a site and user basis.
    Prior to Cylc 8, ``global.cylc`` was named ``global.rc``, but that name is
    no longer supported.
 
+The global.cylc file should be available on user machines (where users interact
+with Cylc on the command line) and on cylc servers (where Cylc schedulers run).
+It is not required to be available on job hosts.
+
+More information about supported configuration items and defaults can be found:
+:ref:`global-configuration`.
+
+Cylc UI Server
+^^^^^^^^^^^^^^
+The `Cylc UI Server`_ can be configured on a site and user basis.
+Guidance for configuration file storage, configuration variables and defaults
+can be found: :ref:`UI_Server_config`.
+
+
 Bash Profile
 ^^^^^^^^^^^^