Skip to content

How to update playbooks

Jump to bottom
Kjetil Klepper edited this page Nov 30, 2021 · 41 revisions

This page describes how to make changes to the Ansible playbooks for the UseGalaxy.no infrastructure. A separate page describes how to run the playbooks. The last part of this page also includes some concrete examples you can consult to solve specific tasks.

The playbooks are stored in a public GitHub repository. You should clone this repo to your local computer and make the changes there. (You don't have to login to UseGalaxy.no to follow the documentation here.)

git clone https://github.com/usegalaxy-no/infrastructure-playbook 
cd infrastructure-playbook

If you already have a clone of the repository, you can just run git pull to get the latest changes.

Ansible code and files that are common to both the test and production setup can be found in the directory env/common. Code specific to the production setup is stored in env/main and code specific to the test setup is stored under env/test.

If you want to make changes to the playbook, you should first create a new feature branch to avoid making direct changes to the main branch.

git checkout -b <name_of_feature_branch>

You can then commit changes to this feature branch as you wish. Remember to include an informative commit message.

git commit -a -m "made some changes to the playbook"

After you have tested the new version of the playbook and confirmed that it works, you can merge your feature branch into the master branch and push it back to GitHub. You can also push your feature branch directly if you want to store it in the repo.

git checkout master
git merge <name_of_feature_branch>
git push origin

Adding secret content

Some information, like passwords and other secret content, should not be included in the playbooks withouth first encrypting them in the Ansible vault. To access the vault, you need to have the password file named vault_password in your current directory. If you don't have this password you can ask another administrator.

You can decrypt an encrypted file with the following command:

ansible-vault decrypt <path_to_encrypted_file>

Afterward decrypting the file, you can edit its contents in a regular text editor. Just remember to always encrypt the file again before you commit it back to the GitHub repository!

Use the following command to encrypt a file:

ansible-vault encrypt <file_to_encrypt>

Examples

Changing configurations in "config/galaxy.yml"

Most of the main configurations in Galaxy are set in the file "config/galaxy.yml". To add or edit configurations in this file, open the playbook file env/common/group_vars/galaxy.yml in a text editor and add the configurations to the galaxy_config block. Note that this block has two sub-blocks, galaxy and uwsgi, similar to the original file. The settings included here will be copied over to the file "/srv/galaxy/config/galaxy.yml" on the Galaxy server.
Text in double-braces, e.g. {{ galaxy_file_path }}, refers to Ansible variables that are defined elsewhere in the same file or in other files (for instance in "env/common/group_vars/global.yml").

...
...

galaxy_config:
  galaxy:
    brand: "Norway"
    admin_users: "{{ galaxy_admin }}"
    master_api: "{{ galaxy_master_api_key }}"
    enable_beta_gdpr: true
    enable_quotas: true
    database_connection: "{{ db_connection }}"
    file_path: "{{ galaxy_file_path }}"
    ...

  uwsgi:
    socket: 127.0.0.1:8080
    buffer-size: 16384
    processes: 4
    ...

Changing configuration files in the "config/" directory

Galaxy relies on several XML and YAML-formatted configuration files normally located in the "config" directory on the server, including

  • dependency_resolvers_conf.xml
  • file_sources_conf.yml
  • job_conf.xml
  • job_metrics_conf.xml
  • tool_conf.xml
  • tool_conf_interactive.xml
  • tool_sheds_conf.xml
  • user_preferences_extra_conf.yml

You can find these files in the playbook either in the directory env/common/files/galaxy/config or in env/common/templates/galaxy/config (if they include Ansible variables that should be substituted). These files are copied over into the "/srv/galaxy/config/" directory on the Galaxy server by actions in the env/common/group_vars/galaxy.yml file.

Adding new files and directories to the Galaxy server

If you need to create new directories or copy files onto the Galaxy server, you can add tasks to do that in the playbook file env/common/tasks/galaxy.yml.

Creating a new directory

You can create a new directory with the Ansible file module by specifying the option "state: directory". The task below creates a subdirectory beneath the galaxy root directory ("/srv/galaxy/") owned by the "root" user with file access rights 755.

- name: directory creation for nels_export_history webhook
  file:
    path: "{{ galaxy_root }}/server/config/plugins/webhooks/nels/"
    owner: root
    group: root
    mode: "0755"
    state: directory

Adding files

You can add a new file to the Galaxy server by placing it somewhere under env/common/files/galaxy/ (in a new subdirectory if relevant) and then use the Ansible copy module to add it to the Galaxy server in the specified destination.

- name: add client webhook patch file.
  copy:
    src: files/galaxy/client/options-menu.js
    dest: "{{ galaxy_root }}/server/client/src/mvc/history/options-menu.js"
    owner: root
    group: root
    mode: "0644"

If the file is a template file containing references to Ansible variables that should be replaced with their definitions when the file is copied onto the server, you should use the template module instead of copy to add the file. Template files should preferably be placed in the playbook directory env/common/templates/galaxy/.

- name: config file for nels history export
  template:
    src: templates/galaxy/webhooks/nels_export_history_config.yml.j2
    dest: "{{ galaxy_root }}/server/config/plugins/webhooks/nels/nels_export_history/config.yml"
    owner: root
    group: root
    mode: "0644"

Note: If you want to add new web content files that should be served under "https://usegalaxy.no/static/", you can just add them to the playbook directory env/common/templates/galaxy/static/. All the files in this directory will be copied into "/srv/galaxy/server/static/" on the Galaxy server by the "Add branding" task. Image files can be placed in the subdirectory static/images.

Other tasks

Some common administration tasks involving playbooks have been documented in separate FAQ pages

Clone this wiki locally