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.3 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 of 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 "#".

Make sure that the two lines that set the parameters

* "tool_config_file" and

* "tool_dependency_dir"

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


Optional configuration steps
----------------------------

Note: The following steps are not necessary to get MiModD accessible
  through Galaxy, but it may be a good idea to configure your new
  Galaxy instance completely while you are at it.


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.


Multi-user production setup of Galaxy
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Hint: As the title says, steps described in this section are only
  relevant if you are planning to have your Galaxy instance accessed
  by users other than yourself.

* check that your *galaxy.ini* file includes the exact following
  parameter settings (all activated, i.e., no leading "#") or modify
  the corresponding lines accordingly:

     debug = False
     use_interactive = False

* connect your Galaxy to a database server as suggested in the
  Galaxy documentation; this is a relatively advanced topic, but
  taking the time to install an actual database server application
  (e.g. PostgreSQL) that Galaxy can use to manage its internal
  database becomes really important when multiple jobs are going to be
  run on your Galaxy instance in parallel.

======================================================================


Integration with MiModD
=======================

This section assumes that you

* have installed and properly configured a local instance of Galaxy
  as described above and

* have installed MiModD following the Standard Installation scheme.

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

Warning: Do not use the "MiModD.enablegalaxy" command, when your
  instance of Galaxy runs **another** standard installation of MiModD
  already. This is going to result in version conflicts and possibly
  unreproducible results.It is safe though to run the command multiple
  times for the **same** installation of MiModD, with other versions
  of MiModD present on your system that are not enabled for this
  Galaxy instance, or in the presence of another MiModD version
  installed from a Galaxy tool shed.

You may want to run:

    mimodd help enablegalaxy
    
for detailed information on the command and when you might want to
call it with additional options.
