Singularity Builder VM

Singularity Builder VM is an easy-to-install virtual machine running a mininmal Debian Linux installation prepared with Sylabs Singularity, allowing to build Singularity images as root user in a sandbox environment. The Builder VM is preconfigured to exchange data between predefined host and guest file systems. Singularity Builder VM must not be confused with the product Singularity Remote Builder, which is a part of the commercially available Sylabs Cloud services.

Click the following link if however you intend to learn more about concepts and usage of Singularity itself.

Supported systems

The Builder VM in its current concept may only be used on (managed) Linux computers. SingularityBuilder VM does only run on ISG.EE managed Linux computers which have been configured to run virtual machines. That is the case for all Tardis clients and some laboratory-owned clients. Older client hardware might not be supported. Contact ISG.EE <> if you want to enable it on your managed client.

Default VM configuration

# Settings might be changed by the user

Maximum VM disk capacity:   30 GB
VM virtual CPU cores:        1 CPU
VM memory size:           6144 MB


You may use any of the ISG.EE managed computers mentioned above to perform the following steps:

  1. Open a Linux terminal
  2. Enter sgbuilder. This will show you an overview/ help on how to install and start the Singularity Builder VM.

  3. Create a new VM copy of the Singularity Builder VM in any directory you like, e.g. /scratch/<Your_Username>/<VM1>:

    sgbuilder install default /scratch/Your_Username/VM1
    Please note you should install your VM somewhere in /scratch and not in your user home directory for performance reasons.
  4. Once the VM has been installed, you can start it up as many times as you want using:

    sgbuilder start /scratch/Your_Username/VM1
  5. To shut down the VM in a clean manner, enter "shutdown now" at the shell.


  1. Startup the Builder VM as described in the Installation section above. The following window appears after some startup seconds.
    • vmwindow.jpg

  2. /root will be the current working directory right after VM startup. This is a 30 GB virtual disk within the VM that can be used to save newly generated Singularity images or a Singularity image sandbox.

  3. /root/home is your ITET user home. This can be used to import or export data (e.g. generated SIF images) from the VM to your regular user home directory and vice versa.

  4. /root/scratch is the /scratch directory of the Linux (host system) computer where you started up the VM using sgbuilder start. This can be used to import or export data from the VM to your computer's /scratch directory and vice versa.

  5. When using Singularity, always ensure the output path (e.g the sandbox directory or Singularity image output location) is somewhere below /root. DO NOT ATTEMPT to save Singularity sandbox data or images directly to /root/home or /root/scratch or any other directory above /root (like the root user's home). Saving Singularity output data directly to the scratch or home won't work, as you cannot store any files there using other user id's or group id's than your own id's. Storing data above /root won't work because that would be on the VM's operating file system disk which has - intentionally - almost no diskspace left.

  6. That said, the idea is to use the VM as follows: first import all data needed from external filesystems into the VM's filesystem. Then do your Singularity image processing and at the end, export the generated Singularity image to an external filesystem.

Tips & tricks

VM usage notes (Do's and Don'ts)

Assigning more CPU's and memory to the VM

If you think the VM's performance is bad, you can assign more virtual CPU cores or memory to it. Please note CPU time and memory are limited resources of the host system. If you specify too many CPU's, not enough or too much memory, the VM might not start up or the the computer running the VM becomes noticeably slower. Changing the CPU count/ memory size should be done when the VM is powered off. Settings will come into effect after the VM is powered up again.

* Example: Change CPU count from 1 (default setting) to 4 virtual CPU's

sgbuilder setcpu 4 /scratch/Your_Username/VM1

* Example: Change VM memory size from 6144 MB (default setting) to 8192 MB

# Memory size must be specified in megabyte [MB] units

sgbuilder setmem 8192 /scratch/Your_Username/VM1

Changing the VM's keyboard settings

The default keyboard setting is "us" (american english keyboard). If you want to change this setting permanently (across reboots), you can edit


within the VM and set another country code, e.g. "ch" for Swiss German keyboards. To make the change immediately effective without rebooting the VM, you can enter

setupcon <keymapcode>
setupcon ch

Accessing the VM from outside

Sometimes you want to copy-paste text from your Linux desktop to the Singularity Builder VM console. You may have noticed however, that copy/ paste from/ to the VM console window does not work. As a workaround, you might access the VM's shell from outside the VM using the VM's ssh or serial console feature. We recommend using ssh, because ssh clients support higher-level terminal emulation, which is often not the case with standard tools for serial console access.

Accessing the VM through ssh

Accessing the VM through serial console

The VM cannot access the network, because it has no IP address

Usually, the IP address is automatically assigned during the VM startup. You may check this entering ip addr within the VM. The network interface used for external connections is ususally named ensNN, e.g. ens33. If it doesn't have a valid IPv4 address, you may either reboot the VM or try to obtain a new IP without rebooting, using dhclient <interfacename>. In our example, the <interfacename> would be ens33.

Services/SingularityBuilder (last edited 2021-06-15 07:00:51 by davidsch)