diff --git a/src/guides/manage-installation.rst b/src/guides/manage-installation.rst index b1e447ff..3dd5ccbe 100644 --- a/src/guides/manage-installation.rst +++ b/src/guides/manage-installation.rst @@ -44,6 +44,17 @@ Update an existing installation If the output notes that an update of the Nextstrain CLI itself is available, run the suggested command (after optionally reviewing the release notes). + .. group-tab:: Singularity (Apptainer) + + Update the Singularity runtime: + + .. code-block:: bash + + nextstrain update singularity + + If the output notes that an update of the Nextstrain CLI itself is available, run the suggested command (after optionally reviewing the release notes). + + .. group-tab:: Ambient (advanced) Update a custom Conda environment. @@ -91,6 +102,20 @@ Troubleshoot a broken installation This should rarely be necessary, but may help if you find yourself with a broken runtime. + .. group-tab:: Singularity (Apptainer) + + Running ``nextstrain check-setup singularity`` will report potential issues. + Make sure there are no errors or warnings reported. + + You can forcibly setup the Singularity runtime again by running: + + .. code-block:: bash + + nextstrain setup --force singularity + + This should rarely be necessary, but may help if you find yourself with a broken runtime. + + .. group-tab:: Ambient (advanced) Running ``nextstrain check-setup ambient`` will report potential issues. diff --git a/src/install.rst b/src/install.rst index 1d5107ab..b85581b3 100644 --- a/src/install.rst +++ b/src/install.rst @@ -184,6 +184,29 @@ Set up a Nextstrain runtime .. include:: snippets/nextstrain-setup-conda.rst + .. group-tab:: Singularity (Apptainer) + + Singularity is a container system freely-available for Linux platforms. It is commonly available on institutional HPC systems as an alternative to Docker, which is often not supported on such systems. + + The Singularity project forked into two separate projects in late 2021: `SingularityCE `__ and `Apptainer `__. Either fork should work with Nextstrain CLI, as both projects still provide very similar interfaces and functionality via the ``singularity`` command. + + .. note:: + + These instructions are for institutional HPC systems that have Singularity installed and configured. You may need to ``module load`` SingularityCE or Apptainer. If you don't have Singularity available, consider using one of the other runtimes or continue by installing `SingularityCE `__/`Apptainer `__. + + 1. Check that Singularity is available in your environment. + + .. code-block:: bash + + singularity --version + + 2. Set up the runtime: + + .. code-block:: none + + nextstrain setup --set-default singularity + + .. group-tab:: Ambient (advanced) .. We use the phrase "custom Conda environment" to refer to a Conda environment managed by the user for use with the ambient runtime. @@ -291,6 +314,33 @@ Try running Augur and Auspice exit + .. group-tab:: Singularity (Apptainer) + + 1. Enter an interactive Nextstrain shell in the current directory (``.``). + + .. code-block:: bash + + nextstrain shell . + + 2. Run Augur. + + .. code-block:: bash + + augur --help + + 3. Run Auspice. + + .. code-block:: bash + + auspice --help + + 4. Exit the Nextstrain shell. + + .. code-block:: bash + + exit + + .. group-tab:: Ambient (advanced) .. note::