Galaxy Installation and Initial Configuration

Installation

Requirements

  • Currently, Galaxy runs under Python 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.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.7 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 git. To see whether the tool is installed on your system, type git on the command line and see whether that brings up a help or an error message. You can obtain git from https://git-scm.com/downloads or, on Linux, via your OS package manager.

Detailed installation instructions for Galaxy can be found at https://galaxyproject.org/admin/get-galaxy/.

The basic sequence of commands to issue is:

git clone https://github.com/galaxyproject/galaxy/
cd galaxy
git checkout -b master origin/master
sh run.sh

You do not have to understand how these commands work, just note that git clone needs internet access to download Galaxy. If you are trying to install Galaxy from behind a proxy and experience problems at the cloning step then this link may be helpful.

The last command, sh run.sh, is how you are actually starting Galaxy. The first time, this will be a long process because a lot of auto-configuration gets done for you - just be patient. Once Galaxy is serving you can start using it. To stop the server just press Ctrl + C.

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 Documentation, 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 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 Documentation, but is required to integrate MiModD into your installation.

Edit the main configuration file

Open the freshly generated galaxy.ini file in a text editor. Its content 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 (all activated, i.e., no leading #) or modify the corresponding lines accordingly:

debug = False
use_interactive = False

In addition, make sure that the two lines that set the parameters

  • tool_config_file and
  • tool_dependency_dir

are active, i.e. remove any leading #.

Take note of the setting of the tool_dependency_dir parameter because you will need it in the next step.

Provide your Galaxy with samtools/bcftools executables

Note

If you have previously installed SAMtools (version 1.x) 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.

Back in the terminal window switch to the folder that is set as tool_dependency_dir in the galaxy.ini file and which we will call <tool_dependency_folder> in the following. The configuration file setting specifies the folder relative to the top-level Galaxy directory so to get from there to the <tool_dependency_folder> you can use:

cd <tool_dependency_folder>

Since you are going to work with high-throughput sequencing data, you are going to deal with the BAM and BCF file formats. To handle these file formats correctly, Galaxy requires SAMtools and bcftools (version 1.x).

The good news is that MiModD already includes functional builds of SAMtools and of bcftools - you just need to tell Galaxy about them.

If you have followed the Standard Installation of MiModD, the executable files that Galaxy needs to find are in the bin subfolder of the MiModD package directory.

You can locate this directory by running:

python3 -m MiModD.config

and looking at the first line of output.

Then from the <tool_dependency_folder>, run the following series of commands (substituting <MiModD_package_path> with the actual path reported above):

mkdir samtools samtools/mimodd_bins samtools/mimodd_bins/bin
cp <MiModD_package_path>/bin/samtools samtools/mimodd_bins/bin/
cp <MiModD_package_path>/bin/bcftools samtools/mimodd_bins/bin/
ln -s mimodd_bins/ samtools/default

This is adapted from the Galaxy documentation page on managing tool dependencies and copies the samtools and bcftools executables from the MiModD installation to a new samtools/mimodd_bins/bin subfolder of your <tool_dependency_folder>, then makes the copied versions the default samtools/bcftools versions for Galaxy by creating a symbolic link default to the mimodd_bins folder.

Warning

Some older versions of Galaxy are affected by a bug that prevents Galaxy from discovering the executables even if you followed the above steps carefully. If you are running an affected version of Galaxy, you will receive the confusing error message:

Traceback (most recent call last):
  File "galaxy/lib/galaxy/jobs/runners/local.py", line 129, in queue_job
    job_wrapper.finish( stdout, stderr, exit_code )
  File "galaxy/lib/galaxy/jobs/__init__.py", line 1200, in finish
    dataset.datatype.set_meta( dataset, overwrite=False )
  File "galaxy/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 you generate or upload a BAM file for the first time.

Similarly, your first use of a BCF file will result in an error message like this:

Traceback (most recent call last):
  File "galaxy/lib/galaxy/jobs/runners/local.py", line 128, in queue_job
    job_wrapper.finish( stdout, stderr, exit_code )
  File "galaxy/lib/galaxy/jobs/__init__.py", line 1221, in finish
    dataset.datatype.set_meta( dataset, overwrite=False )
  File "galaxy/lib/galaxy/datatypes/binary.py", line 573, in set_meta
    raise Exception('Error setting BCF metadata: %s' % (stderr or str(e)))
Exception: Error setting BCF metadata: [Errno 2] No such file or directory

If you see any of these errors, 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

or upgrade your instance of Galaxy to an unaffected version.

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 Admin manual.

Note

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

Connect Galaxy to a database server

Hint

This step is optional, but recommended for a production setup of Galaxy.

If you are planning to ever have your Galaxy accessed by several users simultaneously, you should really, as suggested in the Galaxy documentation, 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 to

  1. run:

    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 of) your Galaxy instance, and python3 refers to the python executable that you used to install MiModD.

  2. (re)start Galaxy

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