Skip to content

Commit

Permalink
Add instructions for singularity runtime
Browse files Browse the repository at this point in the history
  • Loading branch information
victorlin committed Apr 25, 2024
1 parent e0ceb0f commit 8b29c2f
Show file tree
Hide file tree
Showing 2 changed files with 75 additions and 0 deletions.
25 changes: 25 additions & 0 deletions src/guides/manage-installation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down
50 changes: 50 additions & 0 deletions src/install.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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::
Expand Down

0 comments on commit 8b29c2f

Please sign in to comment.