Galaxy Installation and Initial Configuration ============================================= Installation ------------ .. admonition:: 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**. To see whether that is installed on your system, type ``hg`` on the command line and see whether that brings up a help or an error message. If you do not have Mercurial, you can get it from ``__ or via your OS package manager. Detailed installation instructions for Galaxy can be found at ``__. The basic sequence of commands to issue 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 .. Note:: This is described as an optional configuration step in the Galaxy Wiki pages, but is **required** to integrate MiModD into your installation. 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 parameters 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 a *samtools* executable ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. Note:: If you have previously installed SAMtools (version 0.1.19 or earlier) and have the *samtools* command available in your path, you may skip this step. If you are unsure, you can try running ``samtools`` 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). The good news is that, if you are following the `Standard Installation of MiModD `__, then this will include a functional build of SAMtools 0.1.19 - you just need to tell Galaxy about it. The samtools executable that Galaxy needs to find is in the ``bin`` subfolder of the MiModD package directory and is called samtools_legacy (that is because the standard installation also comes with a more recent samtools-1.0). 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 with the actual path reported above):: mkdir samtools samtools/0.1.19 samtools/0.1.19/bin cp /bin/samtools_legacy samtools/0.1.19/bin/samtools cd samtools ln -s 0.1.19/ 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. 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. --------------------- .. _Galaxy Integration: 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: i) make a backup copy of Galaxy's main configuration file (*universe.wsgi.ini* or *config/galaxy.ini* depending on your version of Galaxy). ii) run (possibly with superuser rights):: mimodd enable-galaxy where ```` should be replaced with the path to and including the top-level directory (typically called galaxy-dist) of the Galaxy instance. iii) (re)start Galaxy For details of *using* MiModD from Galaxy see the `Tool Documentation `__ and the section `MiModD and Galaxy `__ in the User Guide.