Skip to content

Commit

Permalink
Use SingularityCE and -ce package name consistently
Browse files Browse the repository at this point in the history
Also remove reference to unmaintained Singularity Desktop for Mac.
  • Loading branch information
dtrudg committed May 19, 2021
1 parent bf7f8f5 commit 86819f9
Show file tree
Hide file tree
Showing 12 changed files with 274 additions and 317 deletions.
2 changes: 1 addition & 1 deletion .circleci/config.yml
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ jobs:
steps:
- checkout
- run:
name: Singularity submodule init
name: submodule init
command: |
git submodule update --init --recursive
- run:
Expand Down
92 changes: 46 additions & 46 deletions admin_quickstart.rst
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,19 @@
Admin Quick Start
=================

This quick start gives an overview of installation of SingularityCE from
source, a description of the architecture of SingularityCE, and
This quick start gives an overview of installation of {Singularity} from
source, a description of the architecture of {Singularity}, and
pointers to configuration files. More information, including alternate
installation options and detailed configuration options can be found
later in this guide.

.. _singularity-architecture:

---------------------------
Architecture of Singularity
---------------------------
-----------------------------
Architecture of {Singularity}
-----------------------------

Singularity is designed to allow containers to be executed as if they
{Singularity} is designed to allow containers to be executed as if they
were native programs or scripts on a host system. No daemon is
required to build or run containers, and the security model is compatible
with shared systems.
Expand All @@ -26,25 +26,25 @@ IPC, and other communication pathways used by locally running programs
are synchronized with the applications running locally within the
container.

Singularity favors an 'integration over isolation' approach to
{Singularity} favors an 'integration over isolation' approach to
containers. By default only the mount namespace is isolated for
containers, so that they have their own filesystem view. Access to
hardware such as GPUs, high speed networks, and shared filesystems is
easy and does not require special configuration. User home
directories, ``/tmp`` space, and installation specific mounts make it
simple for users to benefit from the reproducibility of containerized
applications without major changs to their existing workflows. Where
more complete isolation is important, Singularity can use additional
more complete isolation is important, {Singularity} can use additional
Linux namespaces and other security and resource limits to accomplish
this.

.. _singularity-security:

--------------------
Singularity Security
--------------------
----------------------
{Singularity} Security
----------------------

Singularity uses a number of strategies to provide safety and
{Singularity} uses a number of strategies to provide safety and
ease-of-use on both single-user and shared systems. Notable security
features include:

Expand All @@ -69,43 +69,43 @@ To support the SIF image format, automated networking setup etc., and
older Linux distributions without user namespace support, Singularity
runs small amounts of privileged container setup code via a
``starter-setuid`` binary. This is a 'setuid root' binary, so that
Singularity can perform filesystem loop mounts and other operations
{Singularity} can perform filesystem loop mounts and other operations
that need privilege. The setuid flow is the default mode of operation,
but :ref:`can be disabled <install-nonsetuid>` on build, or in the
``singularity.conf`` configuration file if required.

.. note::

Running Singularity in non-setuid mode requires unprivileged user
Running {Singularity} in non-setuid mode requires unprivileged user
namespace support in the operating system kernel and does not
support all features, most notably direct mounts of SIF
images. This impacts integrity/security guarantees of containers at
runtime.

See the :ref:`non-setuid installation section <install-nonsetuid>` for further
detail on how to install singularity to run in non-setuid mode.
detail on how to install {Singularity} to run in non-setuid mode.

------------------------
Installation from Source
------------------------

Singularity Community Edition can be installed from source directly,
or by building an RPM package from the source. Various Linux
distributions also package Singularity, but their packages may not be
{Singularity} can be installed from source directly,
or by building an RPM package from the source. Linux
distributions may also package {Singularity}, but their packages may not be
up-to-date with the upstream version on GitHub.

To install Singularity directly from source, follow the procedure
To install {Singularity} directly from source, follow the procedure
below. Other methods are discussed in the :ref:`Installation
<installation>` section.

.. Note::

This quick-start that you will install as ``root`` using
``sudo``, so that Singularity uses the default ``setuid``
``sudo``, so that {Singularity} uses the default ``setuid``
workflow, and all features are available. See the :ref:`non-setuid
installation <install-nonsetuid>` section of this guide for detail
of how to install as a non-root user, and how this affects the
functionality of Singularity.
functionality of {Singularity}.


Install Dependencies
Expand Down Expand Up @@ -144,9 +144,9 @@ On Ubuntu or Debian install the following dependencies:
Install Go
----------

Singularity v3 is written primarily in Go, and you will need Go 1.13
{Singularity} v3 is written primarily in Go, and you will need Go 1.13
or above installed to compile it from source. Versions of Go packaged
by your distribution may not be new enough to build Singularity.
by your distribution may not be new enough to build {Singularity}.

The method below is one of several ways to `install and configure Go
<https://golang.org/doc/install>`_.
Expand Down Expand Up @@ -183,26 +183,26 @@ Then, set up your environment for Go.
source ~/.bashrc
Download Singularity from a GitHub release
------------------------------------------
Download {Singularity} from a GitHub release
--------------------------------------------

You can download Singularity from one of the releases. To see a full list, visit
You can download {Singularity} from one of the releases. To see a full list, visit
`the GitHub release page <https://github.com/sylabs/singularity/releases>`_.
After deciding on a release to install, you can run the following commands to
proceed with the installation.

.. code-block:: none
$ export VERSION={InstallationVersion} && # adjust this as necessary \
wget https://github.com/sylabs/singularity/releases/download/v${VERSION}/singularity-${VERSION}.tar.gz && \
tar -xzf singularity-${VERSION}.tar.gz && \
cd singularity
wget https://github.com/sylabs/singularity/releases/download/v${VERSION}/singularity-ce-${VERSION}.tar.gz && \
tar -xzf singularity-ce-${VERSION}.tar.gz && \
cd singularity-ce-${VERSION}
Compile & Install Singularity
-----------------------------
Compile & Install {Singularity}
-------------------------------

Singularity uses a custom build system called ``makeit``. ``mconfig`` is called
{Singularity} uses a custom build system called ``makeit``. ``mconfig`` is called
to generate a ``Makefile`` and then ``make`` is used to compile and install.

.. code-block:: none
Expand All @@ -211,7 +211,7 @@ to generate a ``Makefile`` and then ``make`` is used to compile and install.
make -C ./builddir && \
sudo make -C ./builddir install
By default Singularity will be installed in the ``/usr/local`` directory
By default {Singularity} will be installed in the ``/usr/local`` directory
hierarchy. You can specify a custom directory with the ``--prefix`` option, to
``mconfig``:

Expand All @@ -220,50 +220,50 @@ hierarchy. You can specify a custom directory with the ``--prefix`` option, to
$ ./mconfig --prefix=/opt/singularity
This option can be useful if you want to install multiple versions of
Singularity, install a personal version of Singularity on a shared system, or if
you want to remove Singularity easily after installing it.
Singularity, install a personal version of {Singularity} on a shared system, or if
you want to remove {Singularity} easily after installing it.

For a full list of ``mconfig`` options, run ``mconfig --help``. Here
are some of the most common options that you may need to use when
building Singularity from source.
building {Singularity} from source.

- ``--sysconfdir``: Install read-only config files in sysconfdir.
This option is important if you need the ``singularity.conf`` file
or other configuration files in a custom location.

- ``--localstatedir``: Set the state directory where containers are
mounted. This is a particularly important option for administrators
installing Singularity on a shared file system. The
installing {Singularity} on a shared file system. The
``--localstatedir`` should be set to a directory that is present on
each individual node.

- ``-b``: Build Singularity in a given directory. By default this is
- ``-b``: Build {Singularity} in a given directory. By default this is
``./builddir``.

-------------
Configuration
-------------

Singularity is configured using files under ``etc/singularity`` in
{Singularity} is configured using files under ``etc/singularity`` in
your ``--prefix``, or ``--syconfdir`` if you used that option with
``mconfig``. In a default installation from source without a
``--prefix`` set you will find them under
``/usr/local/etc/singularity``.

You can edit these files directly, or using the ``singularity config
You can edit these files directly, or using the ``{Singularity} config
global`` command as the root user to manage them.

``singularity.conf`` contains the majority of options controlling the
runtime behaviour of Singularity. Additional files control security,
runtime behaviour of {Singularity}. Additional files control security,
network, and resource configuration. Head over to the
:ref:`Configuration files <singularity_configfiles>` section where the
files and configuration options are discussed.

----------------
Test Singularity
----------------
------------------
Test {Singularity}
------------------

You can run a quick test of Singularity using a container in the
You can run a quick test of {Singularity} using a container in the
Sylabs Container Library:

.. code-block:: none
Expand All @@ -274,4 +274,4 @@ Sylabs Container Library:
See the `user guide
<https://www.sylabs.io/guides/\{userversion\}/user-guide/>`__ for more
information about how to use Singularity.
information about how to use {Singularity}.
2 changes: 1 addition & 1 deletion appendix.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
Installed Files
===============

An installation of SingularityCE {InstallationVersion}, performed as root via
An installation of {Singularity} {InstallationVersion}, performed as root via
``sudo make install`` consists of the following files, with ownership
and permissions required to use the `setuid` workflow:

Expand Down
10 changes: 5 additions & 5 deletions conf.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Singularity Container documentation build configuration file, created by
# SingularityCE documentation build configuration file, created by
# sphinx-quickstart on Tue Aug 26 14:19:49 2014.
#
# This file is execfile()d with the current directory set to its
Expand Down Expand Up @@ -44,15 +44,15 @@

# General information about the project.
project = u'SingularityCE Admin Guide'
author = u'SingularityCE Project Contributors'
copyright = u'2017-2021, Sylabs Inc'
author = u'SingularityCE Project Contributors'
copyright = u'2017-2021, Sylabs Inc & Project Contributors'

# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '3.7'
version = '3.8'
# We haven't had release specific docs posted for some time, so set release
# same as version here.
release = version
Expand Down Expand Up @@ -244,7 +244,7 @@

# The title of the document. It defaults to the html_title option
# but can be set independently for epub creation.
epub_title = 'SingularityCE ' + version + ' Administrator Guide'
epub_title = '{Singularity} ' + version + ' Administrator Guide'

# The author of the document. This is put in the Dublin Core metadata.
# It defaults to the author option.
Expand Down
Loading

0 comments on commit 86819f9

Please sign in to comment.