autotoc |
---|
true |
In addition to using the main public Galaxy server (a.k.a. Main), you can install your own instance of Galaxy (what this page is about), create a cloud-based instance of Galaxy, or use one of the ever-increasing number of public Galaxy servers hosted by other organizations.
See Choices for help on deciding which of these options may be best for your situation.
Installing your own Galaxy may be a good choice if you plan to:
- Run a local production Galaxy server because you want to
- install and use tools currently unavailable on public Galaxy servers
- use sensitive data (e.g. clinical patient data)
- process large datasets that are too big for public Galaxies
- plug-in new data sources
- Develop Galaxy tools
- Develop Galaxy itself
- UNIX/Linux or Mac OS X (although you can try with Windows)
- Python 2.7
- Git (optional, see below)
- GNU Make, gcc to compile and install tool dependencies
- Additional tool requirements as detailed in Tool Dependencies
Galaxy's source code is hosted in a GitHub repository. Outlined below are basic options for obtaining the source code so you can use Galaxy. For more information see source code details.
If running a production Galaxy service or creating your own personal Galaxy server, use the latest release branch, which only receives stable code updates. The list of releases is available for viewing.
- If you do not have a Galaxy repository yet or you do not want to update the existing instance, run:
$ git clone -b release_16.10 https://github.com/galaxyproject/galaxy.git
- If you have an existing Galaxy repository and want to update it, run:
$ git checkout release_16.10 && git pull --ff-only origin release_16.10
To obtain Galaxy for development, use the default branch after cloning: dev
. This is the branch that pull requests should be made against to contribute code (unless you are fixing a bug in a Galaxy release).
$ git clone https://github.com/galaxyproject/galaxy.git
Galaxy requires a few things to run: a virtualenv, configuration files, and dependent Python modules. However, starting the server for the first time will create/acquire these things as necessary. To start Galaxy, simply run the following command in a terminal window:
$ sh run.sh
This will start up the Galaxy server on localhost and port 8080. Galaxy can then be accessed from a web browser at http://localhost:8080. After starting, Galaxy's server will print output to the terminal window. To stop the Galaxy server, use Ctrl-c
in the terminal window from which Galaxy is running.
To access Galaxy over the network, modify the config/galaxy.ini
file by changing the host
setting to
host = 0.0.0.0
Upon restarting, Galaxy will bind to any available network interfaces instead of the loopback.
You now have your very own Galaxy instance running - congratulations!
To control Galaxy through the UI (installing tools, managing users, creating groups, etc.), users must become an administrator. Only registered users can become admins. To give a user admin privileges, complete the following steps:
- Add the user's Galaxy login email to the configuration file
config/galaxy.ini
. If the file does not exist, copy it from the provided sample:cp config/galaxy.ini.sample config/galaxy.ini
. - Restart Galaxy after modifying the configuration file for changes to take effect.
- Additional details can be found here.
# this should be a comma-separated list of valid Galaxy users
admin_users = user1@example.com,user2@example.com
Galaxy comes with basic tools pre-installed. To install additinoal tools, follow the instructions on Installing tools into Galaxy from the ToolShed.
To stay up-to-date on new Galaxy features and bug fixes, as well as to discuss future features, consider joining the Galaxy Developers mailing list. See Mailing Lists for other options.
Like any other application, Galaxy directories and Galaxy database tables should be backed up, and any disaster recovery plans should be regularly tested to make sure everything is working as expected.
The above instructions are intended for users wishing to develop Galaxy tools and Galaxy itself. To deploy a production-ready 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 heavily endorsed to prevent database locking issues that can arise with multiple users.
Please see the Running Galaxy in a production environment page for more details.
Galaxy development occurs in GitHub. Changes are stabilized in the release_YY.MM
branches and then merged to master
for each YY.MM.point
release.
To be made aware of new Galaxy releases, please join the Galaxy Developers mailing list. Each release is accompanied by release notes.
At any time, you can check to see if a new stable release is available by using the git log
command:
$ git log ..origin/master
commit 3f314974c9c3742b118518881a6d392123ccc05d
Merge: d8eeaae c78b7b6
Author: Nate Coraor <nate@bx.psu.edu>
Date: Mon Mar 9 22:26:54 2015 -0400
Merge branch 'release_15.03' to master for v15.03
If git log
produces no output, Galaxy is up-to-date. If git log
produces a list of commits, a new version is available. We suggest checking the accompanying release notes first (if the release is to a newer major version of Galaxy), but you can also immediately pull the commits to your local Galaxy clone with:
$ git pull
Note: After pulling changes, the Galaxy server needs to be stopped and restarted with the updated code. Restarting 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 Galaxy code includes structural changes to the database tables. The news brief will alert you if a release contains a database change. After updating and restarting Galaxy, 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 backup your database and 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 good practice 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 using the release tag name from the news brief page and the git checkout
command. For example, to return to the latest version of the January 2015 release, use:
$ git checkout release_15.01
You can also use tags to check out specific releases:
$ git tag
v13.01
v13.01.1
v13.02
...
v14.10.1
v15.01
v15.01.1
v15.01.2
v15.03
Restore the fresh backup if a database update was required, and then restart Galaxy to get back to where you started.
-
Offline start: The initial Galaxy run requires Internet access to download the pre-built Python wheels of Galaxy's dependencies.
-
The basic Galaxy install is a single-user instance and is only accessible by the local user. As with many web-based applications, enable cookies in the web-browser for full functionality.
-
A common practice when using any web browser is to stay current with software updates to maximize performance and security. If moving forward to production server with login enabled, please make sure you and your end-users are current.
-
Some tools shipped with Galaxy have dependencies that need to be satisfied manually. Please see details here.
- Galaxy from an archive
- If you don't have Git (and thus cannot run the
git
command), you can download Galaxy in an archive instead: zipped or tar/gzipped. - Be aware that using archives makes it more difficult to stay up-to-date with Galaxy code because there is no simple way to update the copy.
- If you don't have Git (and thus cannot run the
- Fork Galaxy in GitHub
- If you're doing development or making changes to Galaxy, it is best practice to fork Galaxy in GitHub and update to/from your fork.
- See the GitHub fork documentation for details.
Follow these steps to become an admin for a brand new Galaxy.
Prerequisites
- Galaxy was installed using Git.
- Galaxy was started at least once using
sh run.sh
. - Galaxy is currently stopped. See our documentaion for help stopping Galaxy.
Check the default settings
The default setting for admin_users is: #admin_users = None
. You can check this by running the following command:
$ grep "admin_users" config/galaxy.ini.sample
Create a config/galaxy.ini
file and add yourself as an administrator
The following command will: 1) remove the leading hash (#
) character from the admin_users
line, 2) replace None
with the email address of the user being added as an admin, and 3) create a config/galaxy.ini
file with admin_users
changed. Be careful to type the command exactly as written except for changing admin@email.edu
to be the user's email address.
$ sed 's/#admin_users = None/admin_users = admin@email.edu/' config/galaxy.ini.sample > config/galaxy.ini
Confirm that the new config/galaxy.ini
file is correctly formatted
Running the command below should result in the following output: admin_users = admin@email.edu
$ grep "admin_users" config/galaxy.ini
That's it for the galaxy.ini
file changes!
Start up Galaxy again and create an account - using the same email address - through the Galaxy web interface (if this hasn't been done already). The Admin tab will now appear in the masthead for that account.
Below are simplified instructions for shutting down local Galaxy server. If your configuration is more complicated, getting help from an administrator is recommended.
- If Galaxy was the last process running within a terminal window, bring it into the foreground with the command
fg
and shut down withCtrl-c
. - If Galaxy is one of many processes running in the background within a terminal window, find it with the command
jobs
. The list of jobs will be numbered. Bring the Galaxy job to the foreground with the commandfg <number_of_the_job>
and shut down withCtrl-c
.
- From another terminal window, find all active processes with the command
ps
. The list of processes will each have a process ID (called PID). The target process will be namedpython ./scripts/paster.py serve config/galaxy.ini.sample
. Stop it with the commandkill PID
, where "PID" is the actual process ID number. - If you kill only the process named
sh run.sh
, this will result in conflicts and Galaxy will not restart. If you did this or are simply getting errors when trying to restart Galaxy, the solution is to kill the processpython ./scripts/paster.py serve config/galaxy.ini.sample
before restarting Galaxy again.
- Search all Galaxy administration resources.
- Look into Galaxy KickStart Ansible playbook. To deploy Galaxy on your local machine or on the cloud using Ansible, you can use this playbook. Follow the steps in the docs for details.