search

galaxyproject / ansible-galaxy

An Ansible role for managing a Galaxy server
https://galaxy.ansible.com/galaxyproject/galaxy
58 stars 74 forks source link

readme

Galaxy

An Ansible role for installing and managing Galaxy servers. Despite the name confusion, Galaxy bears no relation to Ansible Galaxy.

Getting started with this module? Check out our Tutorial

Requirements

This role has the same dependencies as the git module. In addition, pip and Python virtualenv are required. These can easily be installed via a pre-task in the same play as this role:

- 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 your git executable is not on $PATH, you can specify its location with the git_executable variable. Likewise with the virtualenv executable and corresponding galaxy_virtualenv_command variable.

Role Variables

Not all variables are listed or explained in detail. For additional information about less commonly used variables, see the defaults file.

Many variables control where specific files are placed and where Galaxy writes data. In order to simplify configuration, you may select a layout with the galaxy_layout variable. Which layout you choose affects the required variables.

Required variables

If using any layout other than root-dir:

If using root-dir:

Optional variables

The galaxy_config_perms option controls the permissions that Galaxy configuration files will be set to. This option has been added in version 0.9.18 of the role and the default value is 0640 (user read-write, group read-only, other users have no permissions). In older versions, the role did not control the permissions of configuration files, so be aware that your configuration file permissions may change as of 0.9.18 and later.

Layout control

Either the root-dir or opt layout is recommended for new Galaxy deployments.

Options below that control individual file or subdirectory placement can still override defaults set by the layout.

Process control with Gravity

The role can manage the Galaxy service using gravity. This is the default for Galaxy 22.05 and later. Additionally, support for the galaxy_restart_handler_name variable has been removed. If you need to enable your own custom restart handler, you can use the "listen" option to the handler as explained in the handler documentation. The handler should "listen" to the topic "restart galaxy".

Galaxy Themes

From release 22.01, Galaxy users can select between different UI themes. You can define themes using the galaxy_themes variable, the syntax of which is the same as the themes_conf.yml file described in the themes training.

The galaxy_manage_themes variable controls whether the role manages theme configs and is automatically enabled if galaxy_themes is defined. If you just want to load the the sample themes from Galaxy's themes_conf.yml.sample without defining your own, you can manually set galaxy_manage_themes to true.

Galaxy Subdomains

From release 22.01 Galaxy can serve different static content and themes per host (e.g. subdomain).

By setting galaxy_manage_subdomain_static: yes you enable the creation of static directories and configuration per host.

In order to use this feature, you need to create the following directory structure under files/ (customizable 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, galaxyproject.org will be displayed otherwise.)
├── <subdomain-name-2>                            
│   └── static
│       ├── dist (optional)
│       │   ├── another-static-image.svg
│       │   └── more-static-content-2.svg
│       └── welcome.html (optional)
... (and many more subdomains)

Where the should exactly match your subdomain's name. The subdirectory static is mandatory, while all subdirectories in static are optional. Which subdirectories and files are copied is managed by the static_galaxy_themes_keys variable.

Also make sure that you set galaxy_themes_welcome_url_prefix, so your welcome pages are templated correctly.

It is mandatory to set the variables under galaxy_themes_subdomains as shown in the example in defaults/main.yml. If you enabled the galaxy_manage_host_filters variable, you can also specify the tool sections that should be shown for each individual subdomain.

Each subdomain can be given its own theme, which is defined under the theme key of the subdomain's entry in galaxy_themes_subdomains. This theme will be the default for the subdomain, and any other themes defined globally for the server will also be available for the user to select. If a subdomain's theme is not defined, the global default is used. An example is provided in defaults/main.yml.

Feature control

Several variables control which functions this role will perform (all default to yes except where noted):

Galaxy code and configuration

Options for configuring Galaxy and controlling which version is installed.

Additional config files

Some optional configuration files commonly used in production Galaxy servers can be configured from variables:

As of Galaxy 21.05 the sample configuration files for these features are in XML, but YAML is supported like so:

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

For example:

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

Path configuration

Options for controlling where certain Galaxy components are placed on the filesystem.

User management and privilege separation

Access method control

The role needs to perform tasks as different users depending on which features you have enabled and how you are connecting to the target host. By default, the role will use become (i.e. sudo) to perform tasks as the appropriate user if deemed necessary. Overriding this behavior is discussed in the defaults file.

systemd

systemd is the standard system init daemon on most modern Linux flavors (and all of the ones supported by this role). If galaxy_manage_systemd is enabled, a galaxy service will be configured in systemd to run Galaxy. This service will be automatically started and configured to start when your system boots. You can control the Galaxy service with the systemctl utility as the root user or with 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

You can use systemd user mode if you do not have root privileges on your system by setting galaxy_systemd_root to false. Add --user to the systemctl commands above to interact with systemd in user mode:

Error documents

Miscellaneous options

Dependencies

None

Example Playbook

Basic

Install Galaxy on your local system with all the default options:

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

If your Ansible version >= 2.10.4, then when you run ansible-playbook playbook.yml you should supply an extra argument -u $USER, otherwise you will get an error.

Once installed, you can start with:

$ cd /srv/galaxy
$ sh run.sh

Best Practice

Install Galaxy as per the current production server best practices:

- 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:
          # listening options
          bind: "unix:{{ galaxy_mutable_config_dir }}/gunicorn.sock"
          # performance options
          workers: 2
          # Other options that will be passed to gunicorn
          # This permits setting of 'secure' headers like REMOTE_USER (and friends)
          # https://docs.gunicorn.org/en/stable/settings.html#forwarded-allow-ips
          extra_args: '--forwarded-allow-ips="*"'
          # This lets Gunicorn start Galaxy completely before forking which is faster.
          # https://docs.gunicorn.org/en/stable/settings.html#preload-app
          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

License

Academic Free License ("AFL") v. 3.0

Author Information

This role was written and contributed to by the following people: