Galaxy Installation and Initial Configuration

Installation

Requirements

  • Currently, Galaxy runs under Python 2.6 or 2.7 (Python 3 is not yet supported).

    This means that you will have to have two different Python versions installed on your system (2.6/7 for Galaxy, Python 3.2 or higher for MiModD). The simplest way to make Galaxy and MiModD use their correct versions is by making Python 2.x available as python and Python 3.x as python3 from your shell.

    You can use python --version and python3 --version from the command line, respectively, to find out what versions of Python are known to your system under the different names.

    The Galaxy installation instructions (see below) also provide an example of how you can manipulate your $PATH variable to make Galaxy use the right Python.

  • The installation procedure for Galaxy requires Mercurial or git. To see whether either tool is installed on your system, type hg or git on the command line and see whether that brings up a help or an error message. You can obtain Mercurial from http://mercurial.selenic.com/wiki/Mercurial or git from https://git-scm.com/downloads or either package via your OS package manager.

Detailed installation instructions for Galaxy can be found at https://wiki.galaxyproject.org/Admin/GetGalaxy.

The basic sequence of commands to issue (assuming you use Mercurial; for git see the link above) to get Galaxy installed in the current working directory is:

hg clone https://bitbucket.org/galaxy/galaxy-dist/
cd galaxy-dist
hg update stable
sh run.sh

Although you do not have to know much about the hg command to install Galaxy, there are two variations to the above hg clone command that you may find useful:

  • if you are trying to install Galaxy from behind a proxy, you may need to specify the proxy that Mercurial should use like this:

    hg --config http_proxy.host=ADRRESS_OF_PROXY:PORT_NUMBER clone https://bitbucket.org/galaxy/galaxy-dist/

    or (for proxies requiring authentication):

    hg --config http_proxy.host=ADRRESS_OF_PROXY:PORT_NUMBER --config http_proxy.user=USERNAME --config http_proxy.passwd=PASSWORD clone https://bitbucket.org/galaxy/galaxy-dist/

  • to install Galaxy into a different directory then the default galaxy-dist, you can append a custom path to the command like for example:

    hg clone https://bitbucket.org/galaxy/galaxy-dist/ ~/my_first_galaxy

Initial configuration

To be able to work with your new Galaxy productively and to integrate MiModD into it, you will have to do a bit more manual configuration work on it:

Note

Most of these steps are also described in the section Running Galaxy in a production environment and on a few scattered other pages of the official Galaxy Admin Wiki, which may be a useful complementary source of information.

Also note that any changes to configuration files will not affect a running instance of Galaxy immediately, but only after restarting it.

All command line examples in this section assume that you are starting out in the top-level directory of your Galaxy instance (i.e., the galaxy-dist directory if you went with the default name).

Generate configuration files from templates

Create a copy of the main configuration template file config/galaxy.ini.sample and name it galaxy.ini. Likewise, copy the file config/tool_conf.xml.sample and name the copy tool_conf.xml.

From the command line this can be done via:

cp config/galaxy.ini.sample config/galaxy.ini
cp config/tool_conf.xml.sample config/tool_conf.xml

This is described as an optional configuration step in the Galaxy Wiki pages, but is required to integrate MiModD into your installation.

Note

If you are working with an old version of Galaxy (not recommended), the main configuration file may be called universe.wsgi.ini instead of galaxy.ini and the files will not be located in the config subdirectory, but in the top-level directory instead. If you never generated the universe.wsgi.ini and tool_conf.xml files, you have to use their corresponding .sample templates to do so now before proceeding.

Edit the main configuration file

Open the freshly generated main configuration file in a text editor. The file consists mostly of configuration settings of the form parameter = value and of comment lines starting with #. Some parameter settings are also deactivated with a leading #.

Check that your file includes the exact following parameter settings or modify the corresponding lines accordingly:

debug = False
use_interactive = False
#filter-with = gzip
tool_config_file = config/tool_conf.xml,config/shed_tool_conf.xml

Note

If you are working with the old-style configuration file universe.wsgi.ini, the last line will have to read:

tool_config_file = tool_conf.xml,shed_tool_conf.xml

Set and create a tool-dependencies directory

Still in the main configuration file, look for a line that sets the parameter tool_dependency_dir.

If the line is deactivated, remove the leading # and set the parameter to a non-existant directory path (relative to the top-level Galaxy directory) that should be used to store dependencies of tool shed tools, e.g., you could use:

tool_dependency_dir = tool-dependencies

This setting is required during Galaxy Tool Shed installations of tools (like MiModD) with external dependencies. In addition, the specified directory is also the place in which to put other manually installed tools that your Galaxy instance may require (see the next step).

From the command line run:

mkdir tool-dependencies

to generate the corresponding directory.

Provide your Galaxy with samtools/bcftools executables

Note

If you have previously installed SAMtools (version 0.1.19 or earlier) and have the samtools and bcftools commands available in your path, you may skip this step. If you are unsure, try running samtools and bcftools from the command line.

Since you are going to work with high-throughput sequencing data, you are going to deal with the BAM file format. To handle BAM datasets correctly, Galaxy requires SAMtools (version 0.1.19 or older). It also needs bcftools to handle binary variant files produced by MiModD.

The good news is that, if you are following the Standard Installation of MiModD, then this will include functional builds of SAMtools 0.1.19 and of bcftools - you just need to tell Galaxy about them.

The executable files that Galaxy needs to find are in the bin subfolder of the MiModD package directory and are called samtools_legacy (that is because the standard installation also comes with a more recent samtools-1.2) and bcftools.

You can locate the MiModD package directory by running:

python3 -m MiModD.config

and looking at the first line of output.

Then cd into the tool-dependencies directory created in the previous step and, from there, run the following series of commands (substituting <MiModD_package_path> with the actual path reported above):

mkdir samtools samtools/0.1.19 samtools/0.1.19/bin
cp <MiModD_package_path>/bin/samtools_legacy samtools/0.1.19/bin/samtools
cd samtools
ln -s 0.1.19/ default
cd ..
mkdir bcftools bcftools/1.2 bcftools/1.2/bin
cp <MiModD_package_path>/bin/bcftools bcftools/1.2/bin/bcftools
cd bcftools
ln -s 1.2/ default

This is adapted from the Galaxy Wiki page on managing tool dependencies and copies the samtools_legacy executable from the MiModD installation as samtools to a new samtools/0.1.19/bin subfolder of your tool-dependencies directory, then makes version 0.1.19 the default samtools version for Galaxy by creating a symbolic link default to the 0.1.19 version folder. The same technique is used to make the bcftools executable available to Galaxy.

Warning

At the time of this writing, the latest versions of Galaxy are affected by a bug that prevents Galaxy from discovering the executables even if you followed the above steps carefully. The Galaxy developers are working on a fix for this, but if you are running an affected version of Galaxy, you will receive the confusing error message:

Traceback (most recent call last):
  File "galaxy-dist/lib/galaxy/jobs/runners/local.py", line 129, in queue_job
    job_wrapper.finish( stdout, stderr, exit_code )
  File "galaxy-dist/lib/galaxy/jobs/__init__.py", line 1200, in finish
    dataset.datatype.set_meta( dataset, overwrite=False )
  File "galaxy-dist/lib/galaxy/datatypes/binary.py", line 320, in set_meta
    proc = subprocess.Popen( args=command, stderr=open( stderr_name, 'wb' ) )
  File "/usr/lib/python2.7/subprocess.py", line 710, in __init__
    errread, errwrite)
  File "/usr/lib/python2.7/subprocess.py", line 1327, in _execute_child
    raise child_exception
OSError: [Errno 2] No such file or directory

when MiModD generates a BAM or BCF file for the first time.

If you see this, you will have to copy the samtools and bcftools executables from the MiModD package directory to a folder in your $PATH, e.g., via:

cp <MiModD_package_path>/bin/samtools_legacy <some_directory_in_$PATH>/samtools
cp <MiModD_package_path>/bin/bcftools <some_directory_in_$PATH>/bcftools

Set up Admin accounts

You and/or some other user(s) may want to have their Galaxy accounts promoted to Admin accounts, which allows these users to access additional configuration options from within the Galaxy web interface. The process is described here in the Galaxy Wiki.

Note

The prospective Admin users should first create personal, password-protected user accounts through the web interface.

Connect Galaxy to a database server

If you are planning to ever have your Galaxy accessed by several users simultaneously, you should really, as suggested in the Wiki, take the time to install an actual database server application (e.g. PostgreSQL) that Galaxy can use to manage its internal database.

Integration with MiModD

This section assumes that you

Then to integrate MiModD into your Galaxy instance, all you have to do is:

  1. make a backup copy of Galaxy’s main configuration file (universe.wsgi.ini or config/galaxy.ini depending on your version of Galaxy).

  2. run (possibly with superuser rights):

    python3 -m MiModD.enablegalaxy <PATH_TO_LOCAL_GALAXY>

    where <PATH_TO_LOCAL_GALAXY> should be replaced with the path to and including the top-level directory (typically called galaxy-dist) of the Galaxy instance, and python3 refers to the python executable that you used to install MiModD.

  3. (re)start Galaxy

For details of using MiModD from Galaxy see the Tool Documentation and the section MiModD and Galaxy in the User Guide.