diff --git a/src/dictionaries/proper_nouns b/src/dictionaries/proper_nouns index 27d509ec8a..6bf59d0500 100644 --- a/src/dictionaries/proper_nouns +++ b/src/dictionaries/proper_nouns @@ -1,50 +1,57 @@ Aldergrove -ana Boolean Booleans Camborne -conda Conda Cylc -cylc Empy Exeter +GScan Gantt Gedit Graphene Graphviz Gregorian -GScan Heathrow +Homebrew Hoverwork IDL Isodatetime -isodatetime Jinja -jinja Jupyter -libmamba -loadleveler -lsf Micromamba -moab Moab Nano -npm -pbs Posix Protobuf Pympler Pyro +Slurm +Trac +Tui +Vuex +ana +conda +coreutils +cylc +isodatetime +jinja +libmamba +loadleveler +lsf +macOS +micromamba +miniconda +moab +npm +pbs pyproject rsync +sed sge slurm -Slurm sqlite svn toml -Trac -Tui -Vuex +uv xtrace diff --git a/src/dictionaries/words b/src/dictionaries/words index b16eb23642..a5f9f8a8b3 100644 --- a/src/dictionaries/words +++ b/src/dictionaries/words @@ -222,6 +222,7 @@ timestep timezone timezones toolbar +toolkit tooltip tooltips tuple diff --git a/src/glossary.rst b/src/glossary.rst index 01f451b55f..1abf417461 100644 --- a/src/glossary.rst +++ b/src/glossary.rst @@ -186,6 +186,12 @@ Glossary If you are not using named or numbered runs, the workflow name will be the same as :term:`workflow id`. + wrapper script + A simple shell script which redirects a command to an environment or + executable. + + See :ref:`installation.what-are-wrapper-scripts` and + :ref:`installation.setting-up-the-cylc-wrapper-script`. external trigger xtrigger diff --git a/src/installation.rst b/src/installation.rst index c35cd68909..2e07233962 100644 --- a/src/installation.rst +++ b/src/installation.rst @@ -3,247 +3,421 @@ Installation ============ -Cylc 8 and its core software dependencies can be installed quickly from Conda -Forge, into a conda environment; or from PyPI, into a Python 3 virtual environment. +.. _Graphviz: https://graphviz.org/download/ +.. _configurable-http-proxy: https://anaconda.org/conda-forge/configurable-http-proxy +Cylc runs on Linux and :ref:`macOS `. We recommend installing it +from `conda-forge `_. -Quick Installation ------------------- -Cylc runs on Unix-like systems including Linux and Mac OS. +Quick Installation (for standalone machines) +-------------------------------------------- -.. admonition:: Supported Python versions +.. tab-set:: - Cylc supports Python 3.12+. + .. tab-item:: Conda (recommended) + :sync: conda -Via Conda (recommended) -^^^^^^^^^^^^^^^^^^^^^^^ + Use either conda, miniconda, mamba or micromamba: -.. code-block:: sub + .. code-block:: bash - $ conda install -c conda-forge cylc-flow + conda install -c conda-forge cylc-flow - # Install the browser-GUI (optional) - $ conda install -c conda-forge cylc-uiserver + And optionally: - # Install Rose support (optional) - $ conda install -c conda-forge cylc-rose metomi-rose + .. code-block:: bash -Via Pip (+npm) -^^^^^^^^^^^^^^ + # install cylc-uiserver (provides the Cylc GUI) + conda install -c conda-forge cylc-uiserver -.. important:: + # install Rose support + conda install -c conda-forge cylc-rose metomi-rose - We recommend installing Cylc versions into virtual environments. - This avoids software dependency conflicts and allows multiple - Cylc versions to be installed on your system. + .. dropdown:: System Dependencies + :color: warning - Without virtual environments, users can inadvertently break Cylc (or other - Python programs) by ``pip``-installing conflicting package versions to - ``$HOME/.local``, which takes precedence over central library locations. + Cylc requires the following packages (not installed by ``conda``): -.. code-block:: sub + * ``bash`` + * GNU `coreutils`_ + * ``ssh`` + * ``rsync`` - $ pip install cylc-flow + And optionally: - # Install the browser-GUI (optional) - # (requires nodejs & npm) - $ pip install cylc-uiserver + * ``mail`` (for automated email functionality) - # Install Rose support (optional) - $ pip install cylc-rose metomi-rose + .. tab-item:: Pip + :sync: pip -There are also certain optional extra requirements which you may choose to -install (already included if installing via Conda): + Use either pip or uv: -.. code-block:: sub + .. code-block:: bash + + pip install cylc-flow + + And optionally: + + .. code-block:: bash + + # install cylc-uiserver (provides the Cylc GUI) + pip install cylc-uiserver + + # install Rose support + pip install cylc-rose metomi-rose + + .. dropdown:: We recommend using a virtual environment + :color: primary + + We recommend installing Cylc in a virtual environment. This + avoids software dependency conflicts and allows you to create new + installations of Cylc on a system without breaking old ones + (see :ref:`installation.what-are-wrapper-scripts`). + + .. dropdown:: System Dependencies + :color: warning + + Cylc requires the following packages (not installed by ``pip``): + + * Python 3.12+ + * ``bash`` + * GNU `coreutils`_ + * ``ssh`` + * ``rsync`` - # Support for running the tutorial workflows - $ pip install 'cylc-flow[tutorial]' + And optionally: - # The GUI with multi-user (hub) support - $ pip install 'cylc-uiserver[hub]' - $ npm install configurable-http-proxy + * ``mail`` (for automated email functionality) + * `Graphviz`_ (used by ``cylc graph`` for displaying workflow graphs) + * `configurable-http-proxy`_ (for multi-user setups; can also be + installed using npm) -You might also want to configure: +Once installed, you might want to configure: * :ref:`Shell auto-completion ` * :ref:`Text editor support ` -.. _non-python-requirements: +.. _installation.distributed-installation: -Non-Python Requirements ------------------------ +Distributed Installation (for networks, HPC and cloud environments) +------------------------------------------------------------------- -.. _Graphviz: https://graphviz.org/download/ -.. _configurable-http-proxy: https://anaconda.org/conda-forge/configurable-http-proxy +Cylc is a distributed system. Cylc :term:`schedulers ` can either +submit jobs locally, or to external :term:`job runners ` such as +PBS or Slurm. -These dependencies are not installed by Conda or pip and may not be available on your -system by default: +With local job submission, it is sufficient to activate your Cylc environment +and run the workflow [4]_. However, when using external job runners or distributing +schedulers over multiple nodes on a network, you will need a mechanism to +intercept ``cylc`` commands and direct them to the environment where Cylc is +installed (because environments do not persist with remote system calls and may +not persist with job submission [1]_). -* ``bash`` -* GNU `coreutils`_ -* ``ssh`` -* ``rsync`` -* ``mail`` (optional - for automated email functionality) +To do this, we use a "wrapper script", a simple shell script which you locate +somewhere in the default ``$PATH``. -The following dependencies are installed automatically by Conda but not by pip: -* `Graphviz`_ (optional - used by ``cylc graph`` for displaying workflow - graphs) -* `configurable-http-proxy`_ (optional - for multi-user setups; can also be - installed using npm) +.. _installation.what-are-wrapper-scripts: -.. seealso:: +What Are Wrapper Scripts? +^^^^^^^^^^^^^^^^^^^^^^^^^ - :ref:`SyntaxHighlighting` +A bare-bones wrapper script might look like this: +.. code-block:: bash -Installing On Mac OS --------------------- + #!/bin/bash -l -.. _Homebrew: https://formulae.brew.sh/ -.. _atrun: https://man.freebsd.org/cgi/man.cgi?query=atrun&sektion=8&format=html + # NOTE: intercept "cylc" calls and direct them to the + # "cylc-environment-name" conda environment + exec conda run -n cylc-environment-name cylc "$@" -Cylc requires some extra packages to function on Mac OS. We recommend -installing them using the `Homebrew`_ package manager: +Name this script ``cylc`` and insert it somewhere in ``$PATH`` and all +``cylc`` command calls will be routed via this environment without the need to +manually activate it first. -.. code-block:: console +Cylc provides a more advanced wrapper script which: - $ brew install bash coreutils gnu-sed +* Supports multiple parallel deployments of Cylc at different versions [2]_. +* Works with Conda, Mamba and Python virtual environments. +* **Doesn't** activate the environment (ensures background jobs submitted by + Cylc consistently run in the system environment, not the Cylc environment [3]_). -You will need to prepend the ``coreutils`` and ``gnu-sed`` installations to -your ``$PATH``, follow the instructions in the ``brew install`` output. -.. note:: +.. _installation.setting-up-the-cylc-wrapper-script: + +Setting Up The Cylc Wrapper Script +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Extract the Cylc wrapper script to a directory within ``$PATH``: + +.. code-block:: sub + + cylc get-resources cylc /cylc + chmod +x /cylc - `atrun`_ (the ``at`` command) does not run out-of-the-box on Mac OS - for security reasons and must be manually enabled. +Then edit the script and adjust ``CYLC_HOME_ROOT`` to the directory which contains your Cylc +environment(s). + +.. dropdown:: How to locate my environments? + :color: muted + + Activate your environment and run ``which cylc``. + + For example, if you get this: + + .. code-block:: console + + $ which cylc + 8.6.4 (/site/apps/cylc-8.6.4/bin/cylc) + + Then your environment is named ``cylc-8.6.4``) and located in + ``/site/apps/``, you should edit the wrapper script like so: + + .. code-block:: diff + + - CYLC_HOME_ROOT="${CYLC_HOME_ROOT:-/opt}" + + CYLC_HOME_ROOT="${CYLC_HOME_ROOT:-/site/apps/}" + + +The wrapper script assumes your Cylc environments follow the naming pattern: + +.. code-block:: sub + + cylc- + # OR + cylc-- .. note:: - Newer version of Mac OS set ``zsh`` as the default shell (as opposed to - ``bash``). You do not need to change this but be aware that Cylc uses - ``bash`` (for job scripts) which has a subtly different syntax. + Developers can set ``$CYLC_HOME_ROOT_ALT`` to point + to their development environments. For example: -.. warning:: + .. code-block:: bash - For Mac OS Versions 10.15.0 (Catalina) and higher, SSH is disabled by - default. The ability to SSH into your Mac OS box may be required for - certain Cylc installations. + CYLC_HOME_ROOT_ALT=${HOME}/.conda/envs - See the `Apple support page - `_ - for instructions on enabling SSH. +You may wish to use the same approach for the ``isodatetime`` command, and, if using +`Rose`_ for the ``rose`` and ``rosie`` commands. +To do so create a symbolic link to the wrapper, for each of these commands: -Advanced Installation ---------------------- +.. code-block:: bash -For distributed and multi-user installation we recommend using Conda and -installing Cylc components only where required. + cd /path/to/directory # the path where you installed the wrapper script + ln -s cylc rose + ln -s cylc rosie + ln -s cylc isodatetime -.. tip:: +Further information on wrapper script functionality and interface can be found +in the header of the script itself. - For examples of Conda environments and installation options see - :ref:`conda environments` for examples and details. -The Cylc Components -^^^^^^^^^^^^^^^^^^^ +Cylc Packages +------------- Cylc is split into a number of components providing different functionality: `Cylc Flow`_ - Provides the scheduler "kernel" of Cylc along with the command line interface. + Provides the scheduler "kernel" of Cylc along with the command line + interface. + + .. dropdown:: Packages and optional extras: + :color: primary + + .. tab-set:: + + .. tab-item:: Conda + :sync: conda + + .. note: Please keep this in sync with https://github.com/conda-forge/cylc-flow-feedstock/ + + ``cylc-flow`` + The full installation, recommended for most uses. + ``cylc-flow-base`` + A minimal package, recommended for installation on job hosts where the + full range of user-facing commands is not required. + + .. TODO: add note about report-timings - but hopefully we'll just wipe + out this caveat? + + .. tab-item:: Pip + :sync: pip + + .. note: Please keep this in sync with https://github.com/cylc/cylc-flow/blob/master/pyproject.toml + + ``cylc-flow[graph]`` + Provides the ``cylc graph`` command for workflow graph + visualisation. + ``cylc-flow[report-timings]`` + Provides the ``cylc report-timings`` command for analysing + job timing information. + ``cylc-flow[tutorials]`` + Provides the dependencies required for the :ref:`Cylc Tutorial`. + + .. dropdown:: Distributed installations: + :color: muted + + Cylc Flow must be installed on all nodes where: + + * The CLI is used. + * Schedulers are run. + * The GUI is run. + * Cylc jobs are submitted to (including HPC compute nodes). + `Cylc UI Server`_ Provides the "Cylc Hub" and the browser-based "Cylc GUI". + + .. dropdown:: Packages and optional extras: + :color: primary + + .. tab-set:: + + .. tab-item:: Conda + :sync: conda + + .. note: Please keep this in sync with https://github.com/conda-forge/cylc-uiserver-feedstock/ + + ``cylc-uiserver`` + The full installation, including `Jupyter Hub`_, recommended for + most uses. + ``cylc-uiserver-base`` + The base package without `Jupyter Hub`_. + ``cylc-uiserver-hub-base`` + The base package with ``jupyterhub-base`` (a cut-down version + of `Jupyter Hub`_). This may be useful if you want to install + `Jupyter Hub`_ with an alternative reverse proxy. + + .. tab-item:: Pip + :sync: pip + + .. note: Please keep this in sync with https://github.com/cylc/cylc-uiserver/blob/master/pyproject.toml + + ``cylc-uiserver`` + The base package without `Jupyter Hub`_. + ``cylc-uiserver[hub]`` + The full installation, including `Jupyter Hub`_, recommended for + most uses. + + You will additionally need to install the `Jupyter Hub`_ dependency + ``configurable-http-proxy`` (e.g, via ``npm``). + + .. note:: + + For more information on the role of `Jupyter Hub`_ see + :ref:`CylcUIServer.architecture`. + + .. dropdown:: Distributed installations: + :color: muted + + Cylc UI Server must be installed on the node(s) where the Cylc GUI + is run. + :ref:`Cylc Rose` - Provides support for `Rose`_ suite configurations in Cylc workflows. + Provides support for `Rose`_ suite configurations in + Cylc workflows. -Installation Types -^^^^^^^^^^^^^^^^^^ + .. dropdown:: Distributed installations: + :color: muted -Cylc install locations may fall into the following "roles": + Cylc Rose must be installed in all of the locations Cylc Flow is + installed (if Rose support is required). -User Machines - Where users write workflows and interact with the command line. -Cylc Servers - Where Cylc schedulers run to manage workflows. -Job Hosts - Where jobs run, e.g. supercomputers or clusters +`Rose `__ + The Rose toolkit for writing, editing and running application configurations. -.. note:: + .. dropdown:: Packages and optional extras: + :color: primary - These roles may overlap. For example, Cylc servers can also be job hosts. + See the Rose installation page: https://metomi.github.io/rose/doc/html/index.html -Recommended Installation -^^^^^^^^^^^^^^^^^^^^^^^^ + .. tab-set:: -User Machines - * `Cylc Flow`_ - * :ref:`Cylc Rose` (if using `Rose`_) -Cylc Servers - * `Cylc Flow`_ - * :ref:`Cylc Rose` (if using `Rose`_) - * `Cylc UI Server`_ -Job Hosts: - * `Cylc Flow`_ - * `Rose`_ (if running Rose applications on the job host) + .. tab-item:: Conda + :sync: conda -.. _managing environments: + .. note: Please keep this in sync with https://github.com/conda-forge/metomi-rose-feedstock/ -Managing Environments -^^^^^^^^^^^^^^^^^^^^^ + ``metomi-rose``: + The full installation, recommended for most uses. + ``metomi-rose-base``: + A minimal package, recommended for installation on job hosts + where the full range of user-facing commands is not required. -For Cylc to run, the correct environment must be activated. Cylc can -not do this automatically. You may need to have multiple Cylc versions -available too. + .. tab-item:: Pip + :sync: pip -We recommend using a wrapper script named ``cylc`` to activate the correct -environment before calling the environment's ``cylc`` command. + .. note: Please keep this in sync with https://github.com/metomi/rose/blob/master/pyproject.toml -Cylc comes with a wrapper that can be adapted to point at your Cylc -environments. Extract it to a directory in your ``$PATH`` like this: + ``metomi-rose`` + The base package. + ``metomi-rose[edit]`` + Provides the ``rose edit`` GUI. Extra dependencies are required + for this, see the Rose installation instructions. + ``metomi-rose[graph]`` + Provides the ``rose metadata-graph`` command. + ``metomi-rose[tutorials]`` + Provides the dependencies for the :ref:`Rose Tutorial`. + ``metomi-rose[disco]`` + Provides the Rosie Disco web service. -.. code-block:: bash + .. dropdown:: Distributed installations: + :color: muted + + Rose must be installed in all of the locations Cylc Flow is + installed (if Rose support is required). + + +.. _installing.macos: - cylc get-resources cylc /path/to/cylc # should be in $PATH - chmod +x /path/to/cylc +Installing On macOS +-------------------- + +.. _Homebrew: https://formulae.brew.sh/ +.. _atrun: https://man.freebsd.org/cgi/man.cgi?query=atrun&sektion=8&format=html -You may need to modify this file for your local installation e.g: +We recommend using the `Homebrew`_ package manager to install the Bash, +coreutils and gnu-sed system dependencies: -.. code-block:: diff +.. code-block:: console + + $ brew install bash coreutils gnu-sed - - CYLC_HOME_ROOT="${CYLC_HOME_ROOT:-/opt}" - + CYLC_HOME_ROOT="${CYLC_HOME_ROOT:-/path/to}" +You will need to prepend the ``coreutils`` and ``gnu-sed`` installations to +your ``$PATH``, follow the instructions in the ``brew install`` output. .. note:: - Developers can set ``$CYLC_HOME_ROOT_ALT`` to point - to their development environments. For example: + `atrun`_ (the ``at`` command) does not run out-of-the-box on macOS + for security reasons and must be manually enabled if you want Cylc to + submit jobs using ``at``. - .. code-block:: bash +.. note:: - CYLC_HOME_ROOT_ALT=${HOME}/.conda/envs + The macOS default shell is ``zsh`` (not ``bash``). You do not need to change + this but be aware that Cylc uses ``bash`` (for job scripts) which has a + subtly different syntax. -You may wish to use the same approach for the ``isodatetime`` command, and, if using -`Rose`_ for the ``rose`` and ``rosie`` commands. + If you do not install ``bash`` (e.g, via Homebrew as mentioned above) you + will get the ancient version Bash (3.2) that comes pre-installed with + macOS. -To do so create a symbolic link to the wrapper, for each of these commands: +.. warning:: -.. code-block:: bash + SSH is disabled by default on macOS. It is required for + :ref:`distributed installations `. - cd /path/to # Using the path where you installed the wrapper script - ln -s cylc rose - ln -s cylc rosie - ln -s cylc isodatetime + See the `Apple support page + `_ + for instructions on enabling SSH. Configuration ------------- -Cylc uses sane and safe defaults and is suitable for use "out of the box", +Cylc uses "safe and sane" 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: @@ -257,14 +431,10 @@ Cylc Flow `Cylc Flow`_ is configured by the :cylc:conf:`global.cylc` file which supports configuration of the system on both a site and user basis. -.. note:: - - 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. +The :cylc:conf:`global.cylc` file should be present on user machines (where +users interact with Cylc on the command line) and on cylc servers +(:cylc:conf:`hosts ` where Cylc +:term:`schedulers ` run). It is not required on job hosts. More information about supported configuration items and defaults can be found: :ref:`global-configuration`. @@ -312,4 +482,19 @@ Text Editors There is support for the ``.cylc`` file format in various text editors. -See :ref:`SyntaxHighlighting` for more details. +See :ref:`syntax highlighting ` for more details. + +| + +.. rubric:: Footnotes + +.. [1] Some job runners may attempt to run the job using the environment it was + submitted in, configuration depending. +.. [2] Software environments cannot be upgraded while running processes are + using them. As Cylc workflows are often long-lived parallel installation + makes it easier to install updates and manage + :ref:`scheduler upgrades `. +.. [3] Cylc can be configured to run job submission in a "clean" environment using + :cylc:conf:`global.cylc[platforms][]clean job submission environment`. +.. [4] Assuming :cylc:conf:`global.cylc[platforms][]clean job submission environment` + has not been configured for the ``localhost`` platform. diff --git a/src/reference/changes.rst b/src/reference/changes.rst index 0332561609..7d09920ad4 100644 --- a/src/reference/changes.rst +++ b/src/reference/changes.rst @@ -508,7 +508,7 @@ when playing workflows in the GUI on :ref:`Cylc Hub`. .. seealso:: - :ref:`managing environments` + :ref:`installation.setting-up-the-cylc-wrapper-script` Cylc Remove ^^^^^^^^^^^ diff --git a/src/user-guide/cheat-sheet.rst b/src/user-guide/cheat-sheet.rst index 7cd7f7f026..14ba18e842 100644 --- a/src/user-guide/cheat-sheet.rst +++ b/src/user-guide/cheat-sheet.rst @@ -82,6 +82,24 @@ stop buttons on an old tape player. You can play, pause or stop a workflow as many times as you like; Cylc will never lose its place in the workflow. +.. _cheat_sheet.upgrading_workflows: + +Upgrading Workflows +------------------- + +When a new version of Cylc is deployed, workflows can be upgraded by restarting +them:: + + # stop the workflow (without waiting for active tasks to complete) + cylc stop --now --now + + # restart the workflow + # (you will be prompted if the version would be changed) + cylc play + # (or skipping interactive prompts) + cylc play --upgrade + + List Workflows -------------- diff --git a/src/user-guide/troubleshooting.rst b/src/user-guide/troubleshooting.rst index 10a6adb371..09c783dfb9 100644 --- a/src/user-guide/troubleshooting.rst +++ b/src/user-guide/troubleshooting.rst @@ -479,7 +479,7 @@ E.G. the following error: Means that ``ssh`` is not installed or not in your ``$PATH``. -See :ref:`non-python-requirements` for details on system requirements. +See :ref:`installation` for details on system requirements. .. _troubleshooting.remote_init_did_not_complete: