Galaxy Docker Image

The Galaxy Docker Image is an easy distributable full-fledged Galaxy installation, that can be used for testing, teaching and presenting new tools and features.

One of the main goals is to make access to entire tool suites as easy as possible. Usually, this includes the setup of a public available web-service that needs to be maintained, or that the Tool-user needs to either setup a Galaxy Server by its own or to have Admin access to a local Galaxy server. With docker, tool developers can create their own Image with all dependencies and the user only needs to run it within docker.

The Image is based on Ubuntu 24.04 LTS and all recommended Galaxy requirements are installed. The following chart should illustrate the Docker image hierarchy we have build to make is as easy as possible to build on different layers of our stack and create many exciting Galaxy flavors.

Breaking changes

:information_source: After a long pause, due to interesting times at the beginning of the "golden 2020s", we are finally back with release 24.1. Many things have changed in Galaxy. It is deployed completely differently and gained many new features with many new dependencies. We recommend starting with a fresh /export folder and contacting us if you encounter any problems.

Table of Contents <a name="toc" />

• Usage
  • Upgrading images
    • PostgreSQL migration
  • Enabling Interactive Tools in Galaxy
  • Using passive mode FTP or SFTP
  • Using Parent docker
  • RabbitMQ Management
  • Flower Webapp
  • Galaxy's config settings
  • Configuring Galaxy's behind a proxy
  • On-demand reference data with CVMFS
  • Personalize your Galaxy
  • Deactivating services
  • Restarting Galaxy
  • Advanced Logging
  • Running on an external cluster (DRM)
    • Basic setup for the filesystem
    • Using an external Slurm cluster
    • Using an external Grid Engine cluster
    • Tips for Running Jobs Outside the Container
• Enable Galaxy to use BioContainers (Docker)
• Magic Environment variables
• HTTPS Support
• Lite Mode
• Extending the Docker Image
  • List of Galaxy flavours
• Integrating non-Tool Shed tools into the container
• Users & Passwords
• Development
• Requirements
• Changelog
• Support & Bug Reports

Usage <a name="Usage" /> [toc]

This chapter explains how to launch the container manually.

At first you need to install docker. Please follow the very good instructions from the Docker project.

After the successful installation, all you need to do is:

docker run -d -p 8080:80 -p 8021:21 -p 8022:22 quay.io/bgruening/galaxy

I will shortly explain the meaning of all the parameters. For a more detailed description please consult the docker manual, it's really worth reading.

Let's start:

• docker run will run the Image/Container for you.

  In case you do not have the Container stored locally, docker will download it for you.

• -p 8080:80 will make the port 80 (inside of the container) available on port 8080 on your host. Same holds for port 8021 and 8022, that can be used to transfer data via the FTP or SFTP protocol, respectively.

  Inside the container a nginx Webserver is running on port 80 and that port can be bound to a local port on your host computer. With this parameter you can access your Galaxy instance via http://localhost:8080 immediately after executing the command above. If you work with the Docker Toolbox on Mac or Windows, you need to connect to the machine generated by 'Docker Quickstart'. You get its IP address from docker-machine ls or from the first line in the terminal, e.g.: docker is configured to use the default machine with IP 192.168.99.100.

• quay.io/bgruening/galaxy is the Image/Container name, that directs docker to the correct path in the docker index.

• -d will start the docker container in daemon mode.

For an interactive session, you can execute:

docker run -i -t -p 8080:80 \
    quay.io/bgruening/galaxy \
    /bin/bash

and run the startup script by yourself, to start PostgreSQL, nginx and Galaxy.

Docker images are "read-only", all your changes inside one session will be lost after restart. This mode is useful to present Galaxy to your colleagues or to run workshops with it. To install Tool Shed repositories or to save your data you need to export the calculated data to the host computer.

Fortunately, this is as easy as:

docker run -d -p 8080:80 \
    -v /home/user/galaxy_storage/:/export/ \
    quay.io/bgruening/galaxy

With the additional -v /home/user/galaxy_storage/:/export/ parameter, Docker will mount the local folder /home/user/galaxy_storage into the Container under /export/. A startup.sh script, that is usually starting nginx, PostgreSQL and Galaxy, will recognize the export directory with one of the following outcomes:

• In case of an empty /export/ directory, it will move the PostgreSQL database, the Galaxy database directory, Shed Tools and Tool Dependencies and various config scripts to /export/ and symlink back to the original location.
• In case of a non-empty /export/, for example if you continue a previous session within the same folder, nothing will be moved, but the symlinks will be created.

This enables you to have different export folders for different sessions - means real separation of your different projects.

To detect when the Galaxy distribution in the image changes, the container writes a marker at /export/.galaxy_export_marker. You can override the marker value with GALAXY_EXPORT_MARKER if you need deterministic export refresh behavior.

You can also collect and store /export/ data of Galaxy instances in a dedicated docker Data volume Container created by:

docker create -v /export \
    --name galaxy-store \
    quay.io/bgruening/galaxy \
    /bin/true

To mount this data volume in a Galaxy container, use the --volumes-from parameter:

docker run -d -p 8080:80 \
    --volumes-from galaxy-store \
    quay.io/bgruening/galaxy

This also allows for data separation, but keeps everything encapsulated within the docker engine (e.g. on OS X within your $HOME/.docker folder - easy to backup, archive and restore. This approach, albeit at the expense of disk space, avoids the problems with permissions reported for data export on non-Linux hosts.

Upgrading images <a name="Upgrading-images" /> [toc]

We will release a new version of this image concurrent with every new Galaxy release. For upgrading an image to a new version we have assembled a few hints for you. Please, take in account that upgrading may vary depending on your Galaxy installation, and the changes in new versions. Use this example carefully!

• Create a test instance with only the database and configuration files. This will allow testing to ensure that things run but won't require copying all of the data.
• New unmodified configuration files are always stored in a hidden directory called .distribution_config. Use this folder to diff your configurations with the new configuration files shipped with Galaxy. This prevents needing to go through the change log files to find out which new files were added or which new features you can activate.

Here are 2 suggested upgrade methods, a quick one, and a safer one.

The quick upgrade method

This method involves less data copying, which makes the process quicker, but makes it impossible to downgrade in case of problems.

If you are upgrading from <19.05 to >=19.05, you need to migrate the PostgreSQL database, have a look