galaxyproject.galaxy

Galaxy

This is an Ansible role designed to install and manage Galaxy servers. It’s important to note that this Galaxy has nothing to do with Ansible Galaxy.

If you want to get started, please check out our Tutorial.

Requirements

This role needs the same dependencies as the git module, along with pip and Python virtualenv. You can easily install these with some initial tasks in the same playbook:

- hosts: galaxyservers
  pre_tasks:
    - name: Install Dependencies
      apt:
        name: "{{ item }}"
      become: yes
      when: ansible_os_family == 'Debian'
      with_items:
        - git
        - python-pip
        - python-virtualenv
    - name: Install Dependencies
      yum:
        name: "{{ item }}"
      become: yes
      when: ansible_os_family == 'RedHat'
      with_items:
        - git
        - python-virtualenv
  roles:
    - galaxyproject.galaxy

If the git command is not found on your $PATH, you can set its location using the git_executable variable. You can do the same for the virtualenv command with the galaxy_virtualenv_command variable.

Role Variables

Not all variables are listed or described here. For more details on less common variables, check the defaults file.

Many variables determine where files are placed and where Galaxy saves data. You can choose a layout using the galaxy_layout variable. Your choice of layout affects which variables are required.

Required variables

If not using the root-dir layout:

galaxy_server_dir: The filesystem path where the Galaxy server code will be installed (cloned).

If using root-dir:

galaxy_root: The root path for a Galaxy deployment, where the Galaxy server code will be installed in a subdirectory.

Optional variables

The galaxy_config_perms option controls permissions for Galaxy configuration files. By default, it is set to 0640 (user read-write, group read-only). In older versions, this role did not manage configuration file permissions, so they may have changed since version 0.9.18.

Layout choices

galaxy_layout: Available layouts are listed in the vars/ folder, and include:
- root-dir: All files in subdirectories under one root directory.
- opt: An FHS-compliant layout using multiple directories, like /opt, /etc/opt, etc.
- legacy-improved: Everything under the Galaxy server directory, similar to run.sh.
- legacy: The previous default layout before galaxy_layout was introduced.
- custom: Default options for custom layouts, which require setting a few variables as described in vars/layout-custom.yml.

For new Galaxy setups, it's recommended to use the root-dir or opt layout.

Options that control specific file or directory placements can still override the defaults set by the layout.

Process control with Gravity

This role can manage the Galaxy service using gravity. This is the default for Galaxy version 22.05 and later. Support for the galaxy_restart_handler_name variable has been removed. If you wish to use a custom restart handler, you can use the "listen" option to the handler as clarified in the handler documentation. The handler should listen for the topic "restart galaxy".

Galaxy Themes

From version 22.01, Galaxy users can choose among different UI themes. You can define themes using the galaxy_themes variable, in the same way as the themes_conf.yml file mentioned in the themes training.

The galaxy_manage_themes variable determines whether the role manages theme configurations and is automatically activated if galaxy_themes is defined. If you want to load the sample themes from Galaxy's themes_conf.yml.sample without creating your own, you can set galaxy_manage_themes to true.

Galaxy Subdomains

Starting with version 22.01, Galaxy can serve different static content and themes per host (e.g., subdomain).

By enabling galaxy_manage_subdomain_static: yes, you allow for the creation of static directories and configurations for each host.

You need to create specific directories under files/ (this can be customized with the galaxy_themes_ansible_file_path variable):

files/galaxy/static
├──<subdomain-name-1>
│   └── static
│       ├── dist (optional)
│       │   └── some-image.png
│       ├── images (optional)
│       │   └── more-content.jpg
│       └── welcome.html (optional, otherwise galaxyproject.org will be displayed.)
├── <subdomain-name-2>                            
│   └── static
│       ├── dist (optional)
│       │   ├── another-static-image.svg
│       │   └── more-static-content-2.svg
│       └── welcome.html (optional)
... (and many more subdomains)

The <subdomain-name-1> must exactly match the name of your subdomain. The static subdirectory is mandatory, while the contents of that subdirectory are optional, controlled by the static_galaxy_themes_keys variable.

Ensure that you set galaxy_themes_welcome_url_prefix to template your welcome pages correctly.

It is essential to define the variables under galaxy_themes_subdomains as shown in the example in defaults/main.yml. If you activated galaxy_manage_host_filters, you can also specify which tool sections should be displayed for each subdomain.

Each subdomain can have its own theme, which is defined under the theme key of that subdomain's entry in galaxy_themes_subdomains. This will be the default theme for the subdomain, while other global themes will also be available for user selection. If a subdomain's theme is not set, the global default will be used. An example can be found in defaults/main.yml.

Feature control

Several variables allow you to control which functions this role performs (all default to yes unless noted otherwise):

galaxy_create_user (default: no): Whether to create the Galaxy user. It's best practice to run Galaxy as a different user, but most production setups use a directory service (like LDAP) for user management. This option is useful for standalone servers and requires superuser permissions.
galaxy_manage_paths (default: no): Whether to create and manage ownership/permissions for Galaxy paths. Requires superuser permissions.
galaxy_manage_clone: Whether to clone Galaxy from the source repository and ensure it’s at a specific version (commit), and set up a [virtualenv][virtualenv] for running it.
galaxy_manage_download: Whether to download and unpack Galaxy from a remote archive url, and set up a [virtualenv][virtualenv] for running it.
galaxy_manage_existing: Whether to take over an already existing Galaxy directory and set up a [virtualenv][virtualenv] for running it. galaxy_server_dir should point to the existing source code.
galaxy_manage_static_setup: Manage "static" Galaxy configuration files, which the Galaxy server can't modify. At minimum, this includes the primary Galaxy configuration file, galaxy.ini.
galaxy_manage_mutable_setup: Manage "mutable" configuration files that the Galaxy server can modify (e.g., when installing tools).
galaxy_manage_database: Upgrade the database schema when new versions are released.
galaxy_fetch_dependencies: Retrieve modules that Galaxy depends on for the Galaxy virtual environment.
galaxy_build_client: Build the Galaxy client application (web UI).
galaxy_client_make_target (default: client-production-maps): Set the type of client build. Options are: client, client-production, and client-production-maps. Refer to Galaxy client readme for details.
galaxy_manage_systemd (default: no): Install a systemd service that starts and stops Galaxy with the system.
galaxy_manage_errordocs (default: no): Install Galaxy-styled HTTP error documents for nginx. Requires write access for the error document directory.
galaxy_manage_cleanup (default: no): Set up a cron job to clean up temporary files created by Galaxy. This requires tmpwatch(8) on RedHat-based systems or tmpreaper(8) on Debian-based systems. Check the galaxy_tmpclean_* variables in the defaults file for details.

Galaxy code and configuration

Variables for managing Galaxy settings and specifying what version to install.

galaxy_config: Controls the contents of Galaxy's configuration file (galaxy.ini by default). This variable is a hash of hashes (dictionaries) used to populate the configuration file. Check the Example Playbooks below for usage.
galaxy_config_files: List of hashes defining files to copy from the control machine, detailing src and dest. For instance, to set job destinations, include the galaxy_config_dir followed by the filename as the dest, e.g., dest: "{{ galaxy_config_dir }}/job_conf.xml". Ensure that the correct setup is reflected in galaxy_config for each file added.
galaxy_config_templates: List of hashes for templates to copy and fill from the control machine.
galaxy_local_tools: List of local tool files or directories to copy from the control machine, relative to galaxy_local_tools_src_dir (default: files/galaxy/tools). Items can be tool filenames or a dictionary with keys for file, section_name, and optionally, section_id. If section_name is not provided, tools will go into a section named Local Tools.
galaxy_local_tools_dir: The directory on the Galaxy server for local tool installations.
galaxy_dynamic_job_rules: List of dynamic job rules to copy from the control machine, based on galaxy_dynamic_job_rules_src_dir (default: files/galaxy/dynamic_job_rules in the playbook).
galaxy_dynamic_job_rules_dir (default: {{ galaxy_server_dir }}/lib/galaxy/jobs/rules): Directory on the Galaxy server for installing dynamic job rules. If modified, ensure it's included in Galaxy's $PYTHONPATH.
galaxy_repo (default: https://github.com/galaxyproject/galaxy.git): The Git repository from which to clone Galaxy.
galaxy_commit_id (default: master): Specifies a commit id, tag, branch, or any valid Git reference for the version of Galaxy.
galaxy_force_checkout (default: no): If set to yes, it will discard any modified files in the Galaxy repository.
galaxy_clone_depth (default: unset): Sets the depth for git clone. Leave empty to clone the full history.

Additional config files

Common optional configuration files for production Galaxy servers:

galaxy_dependency_resolvers: Populate the dependency_resolvers_conf.yml file. Check the sample XML configuration for options.
galaxy_container_resolvers: Populate the container_resolvers_conf.yml file. View the sample XML configuration for options.
galaxy_job_metrics_plugins: Populate the job_metrics_conf.yml file. For options, refer to the sample XML configuration.

As of Galaxy version 21.05, sample configuration files are in XML, but YAML is also supported:

galaxy_dependency_resolvers:
  - type: <XML tag name>
    <XML attribute name>: <XML attribute value>

For instance:

galaxy_dependency_resolvers:
  - type: galaxy_packages
  - type: conda
    prefix: /srv/galaxy/conda
    auto_init: true
    auto_install: false

Path configuration

Variables for managing where certain Galaxy components are located on the filesystem.

galaxy_venv_dir (default: <galaxy_server_dir>/.venv): The role will create a [virtualenv][virtualenv] for running Galaxy, and this variable controls its location.
galaxy_virtualenv_command (default: virtualenv): The command used to create Galaxy's virtual environment. To use Python 3 on Galaxy >= 20.01, set this to pyvenv.
galaxy_virtualenv_python (default: the first virtualenv or python command on $PATH): The Python binary used to create the virtual environment. Use python2.7 for Galaxy < 20.01 and python3.5 or higher for Galaxy >= 20.01.
galaxy_config_dir (default: <galaxy_server_dir>): Directory used for static configuration files.
galaxy_mutable_config_dir (default: <galaxy_server_dir>): Directory for mutable configuration files, must be writable by the Galaxy process user.
galaxy_mutable_data_dir (default: <galaxy_server_dir>/database): Directory for mutable data and caches, must be writable by the Galaxy process user.
galaxy_config_file (default: <galaxy_config_dir>/galaxy.ini): Main configuration file for Galaxy.

User management and privilege separation

galaxy_separate_privileges (default: no): Activates privilege separation mode.
galaxy_user (default: user running Ansible): Name of the system user under which Galaxy operates.
galaxy_privsep_user (default: root): Name of the system user that owns the Galaxy code, configuration files, and virtual environment.
galaxy_group: Common group for Galaxy and privilege separation user. If set and galaxy_manage_paths is activated, directories with sensitive information (like Galaxy's config file) will have restricted group permissions.

Access method control

This role needs to perform tasks as different users based on enabled features and how you connect to the target host. By default, it will use become (or sudo) for tasks that require different user permissions. You can override this behavior as discussed in the defaults file.

systemd

systemd is the common system initialization tool on most modern Linux systems (and all those supported by this role). If galaxy_manage_systemd is enabled, a galaxy service will be set up in systemd to run Galaxy. This service will start automatically at system boot, and you can control the Galaxy service using systemctl commands as the root user or using sudo:

# systemctl start galaxy     # start galaxy
# systemctl reload galaxy    # attempt a graceful reload
# systemctl restart galaxy   # perform a hard restart
# systemctl stop galaxy      # stop galaxy

If you don't have root privileges, you can run systemd in user mode by setting galaxy_systemd_root to false. Just add --user to the previous systemctl commands to control it in user mode.

Error documents

galaxy_errordocs_dir: Directory for installing Galaxy-styled HTTP 413 and 502 error documents. The 502 page uses nginx includes to display a custom message if Galaxy is down. You will need to set up nginx separately for serving these error documents.
galaxy_errordocs_server_name (default: Galaxy): Used to show a message like "galaxy_errdocs_server_name cannot be reached" on the 502 error page.
galaxy_errordocs_prefix (default: /error): Web path to the error document root.

Miscellaneous options

galaxy_admin_email_to: If set, an email will be sent to this address when Galaxy is updated. Assumes the mail system is properly set up on the managed host.
galaxy_admin_email_from: Email address used for sending the notifications mentioned above.

Dependencies

None

Example Playbook

Basic

To install Galaxy on your local machine with default options:

- hosts: localhost
  vars:
    galaxy_server_dir: /srv/galaxy
  connection: local
  roles:
     - galaxyproject.galaxy

For Ansible version >= 2.10.4, run ansible-playbook playbook.yml with an extra argument -u $USER to avoid errors.

After installation, start Galaxy with:

$ cd /srv/galaxy
$ sh run.sh

Best Practice

To install Galaxy following current best practices for production servers:

Galaxy code (the clone) is clean: no configurations or mutable data are stored in its folder.
Galaxy code and static configurations are privileged, not owned or writable by the user running Galaxy.
Configuration files are not accessible to all users.
PostgreSQL is used as the backend database.
YAML configuration style used since version 18.01 is in place.
Two job handler mules are started.
When Galaxy code or configs are updated via Ansible, Galaxy will restart using galaxyctl or systemctl restart galaxy-*.

- hosts: galaxyservers
  vars:
    galaxy_config_style: yaml
    galaxy_layout: root-dir
    galaxy_root: /srv/galaxy
    galaxy_commit_id: release_23.0
    galaxy_separate_privileges: yes
    galaxy_force_checkout: true
    galaxy_create_user: yes
    galaxy_manage_paths: yes
    galaxy_manage_systemd: yes
    galaxy_user: galaxy
    galaxy_privsep_user: gxpriv
    galaxy_group: galaxy
    postgresql_objects_users:
      - name: galaxy
        password: null
    postgresql_objects_databases:
      - name: galaxy
        owner: galaxy
    galaxy_config:
      gravity:
        process_manager: systemd
        galaxy_root: "{{ galaxy_root }}/server"
        galaxy_user: "{{ galaxy_user_name }}"
        virtualenv: "{{ galaxy_venv_dir }}"
        gunicorn:
          bind: "unix:{{ galaxy_mutable_config_dir }}/gunicorn.sock"
          workers: 2
          extra_args: '--forwarded-allow-ips="*"'
          preload: true
        celery:
          concurrency: 2
          enable_beat: true
          enable: true
          queues: celery,galaxy.internal,galaxy.external
          pool: threads
          memory_limit: 2
          loglevel: DEBUG
        handlers:
          handler:
            processes: 2
            pools:
              - job-handlers
              - workflow-schedulers
      galaxy:
        database_connection: "postgresql:///galaxy?host=/var/run/postgresql"
  pre_tasks:
    - name: Install Dependencies
      apt:
        name:
          - sudo
          - git
          - make
          - python3-venv
          - python3-setuptools
          - python3-dev
          - python3-psycopg2
          - gcc
          - acl
          - gnutls-bin
          - libmagic-dev
      become: yes
  roles:
    # Install with:
    #   % ansible-galaxy install galaxyproject.postgresql
    - role: galaxyproject.postgresql
      become: yes
    # Install with:
    #   % ansible-galaxy install natefoo.postgresql_objects
    - role: galaxyproject.postgresql_objects
      become: yes
      become_user: postgres
    - role: galaxyproject.galaxy