How to find the container for a particular tool

Tools that specify <requirements> in their tool wrappers will be executed in custom-built Singularity containers on UseGalaxy.no. (Tools without explicit requirements will run in a default container which includes the following packages).

The Singularity image for a tool is created the first time the tool is executed and will be placed in the directory: /srv/galaxy/containers/singularity/mulled/

For tools that only have a single requirement, the Singularity image will be named after the tool name and version (and possibly also build), as specified in the tool wrapper, e.g. "gnuplot:5.2.3" or "krona:2.7.1--pl526_4". If the tool has multiple requirements, Galaxy will build a mulled container that contains all the required packages. The name of this mulled container will start with "mulled-v2-", followed by an uninformative hash string based on the concatenated names of all the requirements, then a colon and finally another hash string based on the versions of all the requirements. (If all requirements are versionless, this second hash would just be the number 0.)

There are two ways you can find the name of the container image for a tool with multiple requirements. In both cases you need to know already what these requirements are, and you can find them in the tool wrapper XML file. If the tool is installed on a Galaxy server, you can click on the tool in the Tools Panel to bring up the execution form and then press the "Options" button in the page header. Select "See in Tool Shed" from the popup menu. In the tool shed, click on the link with the "Name:" of the tool (or press the “Repository Actions” button in the top-right corner and select "Browse repository tip files"). On the next page, locate the "Contents:" box (looks like a file browser) and click on the tool wrapper XML file to display it. You should be able to find the <requirements> block near the top of this file (alternatively, it could be included in a “macros.xml” file in the same directory).

1. Finding the container name from the BioContainers web site

If the required packages are available from the "best practice" Conda channels (i.e. either "iuc", "conda-forge", "bioconda" or "defaults"), you can use a service on the BioContainers web site to find the container image name. Go to https://biocontainers.pro/multipackage and enter the name of the first tool requirement in the search box. Find the correct version (according to the tool wrapper) and click on the + sign in the last column. A new panel should now appear on the right which lists all the packages you have selected so far. The box at the bottom of this panel will contain the name that BioContainers will assign to a container with these packages. Search for the second requirement and add this also. The name of the container should now change to a mulled container name which starts with "mulled-v2-" (after the "quay.io/biocontainers/" prefix) and is followed by a hash string that is derived from the list of package names and versions. Add the rest of the required packages to get the final name. Note that the order of the requirements is important since the hash string will be different if the packages are listed in a different order. So you must specify the requirements in the exact order they are listed in the tool wrapper! Note also that the name of the container in Galaxy's container directory will start with the name you found but it could also have additional build suffixes behind it.

2. Finding the container name by running Galaxy code manually

An alternative way to find the container name is to log into UseGalaxy.no with SSH and manually run a function to generate the container name. This is the only available option if the dependencies cannot be found in the "best practice" Conda channels. (Update: this has now been simplified with a new script. See section 3 below.)

source /srv/galaxy/venv/bin/activate
cd /srv/galaxy/server/lib/galaxy/tool_util/deps/mulled
python -c "from util import *; print(v2_image_name(XXXX))"

The XXXX parameter on the last line should be replaced with a Python list of packages, where each package is specified with a call to "build_target()" by supplying the name and (optionally) version of the tool. E.g.:

[ build_target('samtools', version='1.3.1'), build_target('bwa', version='0.7.15') ]

See the util.py file for more information, if necessary. The container name should be on the format "mulled-v2-NNNNN:vvv" where NNNNN is a hash-string based on the names of the requirements and vvv is another hash-string based on the versions of the requirements. If all the tools are versionless, the :vvv may be missing, in which case you should add a :0 to the end of the name to avoid problems with a bug in Galaxy.

3. Finding the container name with a new script

A simple Python-script has been created in /usr/local/bin/find_container_id.py to simplify the process described above. It just takes the tool-wrapper XML-file containing the requirements as input, and it will output a list of the requirements found in the wrapper plus the (mulled) name of the resulting container. If the location of the script is in your $PATH (and it should be), you can execute it with the command:

find_container_id.py <tool_wrapper.xml>

When run this way, the script will be executed by the Python version included in Galaxy's virtual environment. This is necessary for it to function, since it relies on certain dependencies that are included in Galaxy.