Running Singularity with Vagrant

Setting Up VirtualBox and Vagrant on Windows or Mac

If you do not have access to a Linux machine and need to run Singularity on Windows or Mac, use this tutorial go set up a Vagrant-based Linux instance.

The steps we outline for Vagrant initial setup and installation are based on the Singularity documentation found here: https://sylabs.io/guides/3.5/admin-guide/installation.html

Note: Our containers are built on Singularity v3.5, please refer to documentation and VM's for that version.

Following basic installation of Vagrant, we recommend additional steps for binding a local folder to the VM instance to facilitate running CERR container pipelines. Documentation for configuring "synced folders" in Vagrant: https://www.vagrantup.com/docs/synced-folders/basic_usage

1. Install the following prerequisites:

Windows

• Git for Windows provides a bash shell command prompt
• VirtualBox (Vagrant is compatible with VirtualBox versions 4.0.x, 4.1.x, 4.2.x, 4.3.x, 5.0.x, 5.1.x, 5.2.x, 6.0.x, and 6.1.x)
• Vagrant for Windows
• Vagrant Manager for Windows (optional)

Mac

Note: There is a Singularity Desktop client for macOS currently in Beta, available here. The instructions on this page are specifically related to usage of Vagrant for running Singularity and do not cover Singularity Desktop.

Vagrant can be installed via Homebrew using the following commands:

    $ /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
    $ brew cask install virtualbox && \
            brew cask install vagrant && \
            brew cask install vagrant-manager`

2. Setup Singularity Ubuntu (Linux) VM

• Open a terminal (in Windows, use git bash in admin mode) and find out what your current directory is:

  $ pwd
  

• Create a directory called vm_singularity and cd into it.

  $ export VM_SING=/c/work/containers/vm_singularity && mkdir -p $VM_SING && cd $VM_SING
  

• Download and initialize the base image. This will create a Vagrant file in the $VM_SING folder.

  $ export VM=sylabs/singularity-3.5-ubuntu-bionic64 && vagrant init $VM 
  

Note: Optional argument can be passed on the call to vagrant init to use specific locally-installed version of VirtualBox, ie:

    $ vagrant init $VM --box-version 20190529.0.0'

3. Modify Vagrantfile configuration for synced folder

• To mount a local folder in the VM, edit the Vagrantfile and add the following just before the closing “end” at the bottom:

  config.vm.synced_folder "SIFfiles", "/vagrant"
  

And create a folder called SIFfiles under $VM_SING. Alternatively, absolute paths can be used to specify folders outside of the $VM_SING root.

    $ mkdir ${VM_SING}/SIFfiles

• Copy the Singularity container to execute into this SIFfiles directory. Everything under here will be visible in the vagrant VM.

4. Final steps, start Vagrant instance, install Singularity

• Install Virtual Box Guest Additions by installing the vagrant plugin for it:

    $ vagrant plugin install vagrant-vbguest
  

• Start the Ubuntu VM:

    $ vagrant up
  

• ssh into the VM

    $ vagrant ssh
  

• Once logged into Vagrant machine prompt, install Singularity 3.5. It is very straightforward to follow in the steps in the QuickStart guide