In addition to using the public Galaxy server (a.k.a. Main), you can also install your own instance of Galaxy (what this page is about), or create an instance of Galaxy on the cloud. Another option is to use one of the ever-increasing number of Public Galaxy Servers hosted by other organizations.

See Big Picture/Choices for help on deciding which of these options may be best for your situation.

Reasons to Install Your Own Galaxy

You only need to download Galaxy if you plan to:

1. Develop it further

2. Add new tools

3. Plug-in new datasources, or

4. Run a local production server for your site because you have

   1. Sensitive data (e.g., clinical)

   2. Large datasets or processing requirements that are too big to be processed on Main

Installation Procedure

The installation procedure is simple and is nearly identical for UNIX/Linux and Mac OS X. We are no longer supporting the Windows platform with our distribution, so you will have to build your own Python eggs if you want to install it on Windows (see Admin/Config/Windows for some tips). Of course, Windows users can use our public Galaxy server from their browsers.

These instructions describe the basic setup procedure for a development environment, more detailed instructions on how to deploy a production server can be found at the bottom of this page.

Check your Python version

Galaxy's core functionality is compatible with Python versions 2.5, 2.6, and 2.7. (Version 2.4 support was last included in the November 18, 2011 Distribution). Before reporting bugs, please ensure that python --version reports one of these three versions. If this is not the case, a simple solution is to manipulate your shell's $PATH variable to place the correct version first. This can be done for only Python by creating a new directory at the front of $PATH and creating a symbolic link to python in that directory:

   1 % mkdir ~/galaxy-python
   2 % ln -s /path/to/python2.5 ~/galaxy-python/python
   3 % export PATH=~/galaxy-python:$PATH

If you've compiled your own Python interpreter from source, please ensure that the ssl and bz2 modules build and can be imported after installation.  These "extra" modules are built at the end of the compilation process and are required by the Galaxy framework.  If building on Linux, you may need to install the appropriate -dev packages for OpenSSL and Bzip2.

Get the latest copy from the repository

The latest source code can be downloaded from the anonymous Mercurial repository with this command:

   1 % hg clone https://bitbucket.org/galaxy/galaxy-dist/
   2 % hg update stable
   3 236 files updated, 0 files merged, 152 files removed, 0 files unresolved

You can switch between the current "stable" and "in-development" code (where in-development code is on the default branch) with:

   1 % hg update default
   2 246 files updated, 0 files merged, 142 files removed, 0 files unresolved
   3 % hg update stable
   4 236 files updated, 0 files merged, 152 files removed, 0 files unresolved

Either branch can be used for development, although if submitting code back to the Galaxy Team (i.e. via a pull request in Bitbucket), you should create those pull requests against default.

If you don't have Mercurial, tarballs can be downloaded instead: zipped, gzipped, or bzipped. However, this makes it more difficult to stay updated in the future since there's no simple way to update your copy.

Start it up

Galaxy requires a few things to run - configuration files, and dependent Python modules called "eggs". However, starting the server for the first time will create/acquire these things as necessary. Simply run the following command:

   1 % sh run.sh

This will start up the server on localhost and port 8080, so Galaxy can be accessed from your web browser at http://localhost:8080 . To stop the Galaxy server, just hit Ctrl-c in the terminal from which Galaxy is running.

As shown, Galaxy is run locally and developers do not need any special environment for running and developing its code.

To access Galaxy over the network, simply modify the universe_wsgi.ini file and change the host setting to

   1 host = 0.0.0.0

Upon restarting, Galaxy will bind to any available network interfaces instead of just the loopback.

Some tools do have outside dependencies that cannot be provided with Galaxy for various reasons. The list of these dependencies can be found on the Admin/Tools/Tool Dependencies page. Also, the initial run requires internet access to download the pre-built Python eggs on which Galaxy runs. If the system on which you are installing Galaxy does not have Internet access, please follow the instructions for offline systems on Admin/Config/Eggs before starting the server.

If using Python 2.6 or 2.7, you may encounter a bug which prevents Ctrl-c from shutting down the Galaxy process. If this is the case, starting Galaxy with

   1 sh run.sh --reload

will work around this problem.

Join the Mailing List

The best way to keep up on new features and bug fixes, as well as discuss future features is to join the Galaxy Developers mailing list. See Mailing Lists for other options.

Keep your instance backed up

Like any other application, your Galaxy directory and your Galaxy database tables should be backed up and your disaster recovery plan should be regularly tested to make sure everything is working as expected.

Keep your code up to date

Galaxy development occurs in two repositories, galaxy-central and galaxy-dist. Changes are stabilized in galaxy-central and then pushed to galaxy-dist roughly once a month. The Galaxy clone you acquired in Step 1 is of the stable distribution (galaxy-dist).

To be made aware of new stable releases, please join the Galaxy Developers mailing list. Each stable release is accompanied by a news brief.

At any time, you can check to see if a new stable release is available by using the hg incoming command:

   1 % hg incoming
   2 comparing with https://bitbucket.org/galaxy/galaxy-dist/
   3 searching for changes
   4 no changes found

If instead you see a list of changesets, a new distribution is available. We suggest checking the accompanying news brief first, but you can also immediately pull the changesets to your local Galaxy clone with:

% hg pull -u
...

Note: After pulling changes, you will need to stop your Galaxy server and restart with the updated code. This will interrupt any running jobs, unless you are using a cluster configuration. For more information on how to make Galaxy restartable without interrupting users, see the production server documentation.

Note: Occasionally, updated code includes structural changes to the Galaxy database tables. The news brief will alert you if a release contains a database change. After updating Galaxy, if you attempt to restart, Galaxy will refuse to load, and will output an error message indicating that your database is the wrong version. The error message indicates that you should run backup your database and then run sh manage_db.sh upgrade - follow those instructions carefully - especially the part about backing up your database safely! Database updates are carefully tested before release, but it is always wise to be able to back out if something goes wrong during an update.

In the unlikely event that something goes wrong with updated code, you can return to an older release by getting the release changeset id from the news brief page and using the hg update command. For example, to return to the December 3, 2012 release, use:

   1 % hg update -r f364d992270c

Restore the fresh backup if a database update was required, and then restart Galaxy to get back to where you started.

Advanced Configuration

The above instructions are intended for those wishing to develop tools and the Galaxy framework. To deploy a local site installation of Galaxy, some changes from the default configuration are highly recommended. If nothing else, switching to PostgreSQL or MySQL (from the default SQLite) is highly recommended to prevent database locking issues that can arise with multiple users.

Please see the Running Galaxy in a production environment page for more details.

Other Help

• Support

• Search all Galaxy administration resources

• Mailing Lists

• Other tutorials / logs

  • Notes on installing Galaxy by Paul-Michael Agapow at BioCoders.net; posted 2012/02/20.