From 8b29c2f846358612ed461d5cf2456ec9de4e56ae Mon Sep 17 00:00:00 2001
From: Victor Lin <13424970+victorlin@users.noreply.github.com>
Date: Wed, 31 Jan 2024 10:22:56 -0800
Subject: [PATCH] Add instructions for singularity runtime

Descriptive snippet copied from Nextstrain CLI docs.

<https://github.com/nextstrain/cli/blob/6da49c541/nextstrain/cli/runner/singularity.py>
---
 src/guides/manage-installation.rst | 25 +++++++++++++++
 src/install.rst                    | 50 ++++++++++++++++++++++++++++++
 2 files changed, 75 insertions(+)

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 <https://sylabs.io/singularity/>`__ and `Apptainer <https://apptainer.org>`__.  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 <https://docs.sylabs.io/guides/3.0/user-guide/installation.html>`__/`Apptainer <https://apptainer.org/docs/admin/main/installation.html>`__.
+
+      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::