Skip to content
Snippets Groups Projects
use_singularity.rst 4.28 KiB
Newer Older
  • Learn to ignore specific revisions
  • Dmitry Romanov's avatar
    Dmitry Romanov committed
    Use singularity
    ===============
    
    Install singularity
    -------------------
    
    The `oficial installation instructions <https://sylabs.io/guides/3.0/user-guide/installation.html>`_ have many steps. 
    Please don't install NeuroDebian repo from the repo as it holds v2.6 and eic image require singularity > 3.0.
    
    Instead. If you have ubuntu, there is a `debian repo with 3.5.2 version <https://packages.debian.org/source/sid/singularity-container>`_, 
    which works pretty nicely (You will have to install dependencies, it will print them...)
    
    
    .. code:: 
    
    
    Dmitry Romanov's avatar
    Dmitry Romanov committed
       sudo apt install containernetworking-plugins
    
    Dmitry Romanov's avatar
    Dmitry Romanov committed
       wget http://ftp.fi.debian.org/debian/pool/main/s/singularity-container/singularity-container_3.5.2+ds1-1_amd64.deb
    
    Dmitry Romanov's avatar
    Dmitry Romanov committed
       sudo dpkg -i singularity-container_3.5.2+ds1-1_amd64.deb
    
    Dmitry Romanov's avatar
    Dmitry Romanov committed
    
       
    
    Install work environment
    ------------------------
       
    The below command automatically creates the right working environment for detector development. 
    It checks if there are CVMFS images available (which is true for JLab and BNL farms) and links them or downloads images (which is a scenario for users laptops). 
    It also creates eic_shell with the right environment setup, prepares the current dir to work with detector or etc. 
    
    
    .. code::
       
       curl https://eicweb.phy.anl.gov/containers/eic_container/-/raw/master/install.sh | bash
    
    
    CVMFS
    -----
    
    For farms like at BNL or JLab the image is automatically replicated to CVMS:
    
    .. code:: 
    
       singularity run /cvmfs/singularity.opensciencegrid.org/eicweb/jug_xl:3.0-stable
    
    
    Custom work environment 
    -----------------------
    
    #. Clone the repository and go into the directory
    
       .. code-block:: bash
    
          git clone https://eicweb.phy.anl.gov/containers/eic_container.git
          cd eic_container
    
    #. Run the install script ``install.py`` to install to your ``<PREFIX>`` of choice 
       (e.g. $HOME/local/opt/eic_container_1.0.4). By default the
       modeuefile will be installed to ``$PREFIX/../../etc/modulefiles``. 
       You can use the ``-v`` flag to select the version you want to install, or omit the 
       flag if you want to install the master build. The recommended stable 
       release version is ``v2.6.1``.
    
       .. code-block:: bash
    
          ./install.py -v 2.6.1 <PREFIX>
    
       Available flags:
    
       .. code-block:: bash
    
          -v VERSION, --version VERSION 
                               (opt.) project version. Default: current version (in repo).
          -b BIND_PATHS, --bind-path BIND_PATHS
                               (opt.) extra bind paths for singularity.
          -m MODULE_PATH, --module-path MODULE_PATH
                               (opt.) Root module path where you want to install a
                               modulefile. D: <prefix>/../../etc/modulefiles
          -l, --local           Local install, will not install the modulefiles (you will have
                               to run the launcher scripts from their relative paths).
          -f, --force           Force-overwrite already downloaded container with the same name.
    
    
    #. To use the container in installed mode, you can load the modulefile, 
       and then use the included apps as if they are native apps on your system!
    
       .. code-block:: bash
    
          module load eic_container
    
    #. To use the container in local mode, you can install the container with the ``-l`` flag,
       and then use the runscripts (under ``$PREFIX/bin``\ ) manually.
    
       .. code-block:: bash
    
          ./install.py $PREFIX -l
          ...
          $PREFIX/bin/eic-shell
    
    #. (Advanced) If you need to add additional bind directives for the internal singularity container,
       you can add them with the ``-b`` flag. Run ``./install.py -h`` to see a list of all
       supported options.
    
    
    
    Modulefiles
    ^^^^^^^^^^^
    
    Running the singularity development environment with modulefiles
    
    
    #. Add the installed modulefile to your module path, e.g.,
    
       .. code-block:: bash
    
          module use <prefix>/../../etc/modulefiles
    
    #. Load the eic container
    
       .. code-block:: bash
    
          module load eic_container
    
    #. To start a shell in the container environment, do
    
       .. code-block:: bash
    
          eic-shell
    
    
    Without modulefiles
    ^^^^^^^^^^^^^^^^^^^
    
    Running the singularity development locally (without modulefiles)
    
    1. This is assuming you installed with the ``-l`` flag to a prefix ``$PREFIX``\ :
    
       .. code-block:: bash
    
          ./install.py $PREFIX
    
    2. To start a shell in the container environment, do
    
       .. code-block:: bash
    
          $PREFIX/bin/eic-shell