name: inverse
layout: true
class: center, middle, inverse

</span></div>

</span></div>

---

# Upgrading Galaxy

.footnote[Tip: press `P` to view the presenter notes]

???
Presenter notes contain extra information which might be useful if you
intend to use these slides for teaching.

Press `P` again to switch presenter notes off

Press `C` to create a new window where the same presentation will be displayed.
This window is linked to the main window. Changing slides on one will cause the
slide to change on the other. Useful when presenting.

---

### <i class="far fa-question-circle" aria-hidden="true"></i><span class="visually-hidden">question</span> Questions

- What is the release cycle of Galaxy?

- What do I need to do before updating my Galaxy server?

- How to upgrade Galaxy to a new release?

---

### <i class="fas fa-bullseye" aria-hidden="true"></i><span class="visually-hidden">objectives</span> Objectives

- Identify the challenges involved in the Galaxy upgrade process.

- Complete the upgrade to a new release.

---

# Release Cycle

* Galaxy aims to release every 4 months
* Releases are named after the **year** and **month** when the release was branched, for example 18.01, 18.05
* Per the [security policy](https://github.com/galaxyproject/galaxy/blob/dev/SECURITY_POLICY.md), releases within the past 12 months are supported

---
# Releases

* Every release has [release notes](https://docs.galaxyproject.org/en/master/releases)
  * We put substantial effort in making them as useful as we can
  * Highlights, security announcements, deprecation notices, enhancements grouped by impact, etc...
* Every release has its own branch in the `galaxy` GitHub repository
  * Named as `release_YY.MM`
  * Kept up to date (especially for recent releases)

---
# Ansible

We recommend setting up, managing, and upgrading Galaxy using the Ansible software management tool. Please see the materials under 'Galaxy Installation with Ansible'.

When you use Ansible the majority of this slide deck is not relevant anymore since everything mentioned becomes a trivial change in your playbook configuration. Use Ansible if you can.

---
class: left
# Deal with local Galaxy modifications

Two scenarios:
1. Uncommitted changes
2. Changes committed to a local branch (or to a fork)

Don't use a Galaxy with uncommitted changes. Make a branch (it's easy) and commit your changes.

---
# Config Files

Configs you change (galaxy.yml, job_conf.xml, dynamic job rules, ...) should live in version control and be installed outside the Galaxy server directory.

How to store outside Galaxy server dir?

- galaxy.yml: Start Galaxy with `uwsgi --yaml /path/to/galaxy.yml`
- all other configs: Set correct path in `galaxy.yml`

The galaxyproject.galaxy Ansible role can maintain these paths for you.

---
class: left
# Keeping a release up to date (1)

If there are *no local commits*, you can update a `release_YY.MM` branch by running:

```console
$ git pull --ff-only
```

and restarting Galaxy.

The galaxyproject.galaxy Ansible role can perform this update for you.

---
class: left
# Keeping a release up to date (2)

In case of changes committed to a local branch:

```console
$ git pull [--rebase] origin release_YY.MM
```

and restart Galaxy.

---
class: left
# Major release upgrade

When you upgrade to a new release:
* Plan a service downtime for the upgrade and inform your users
* Configure your reverse proxy to serve a custom error page (the galaxyproject.galaxy Ansible role can do this for you), e.g. for nginx inside the `server` section add:
  ```ini
  error_page 502 /static/custom_502.html;
  ```
* When it's time, stop the Galaxy server processes (not the database server!)

---
class: left
# Housekeeping

Not usually necessary, but might help:

```console
$ find . -name '*.pyc' -delete
$ rm -rf database/compiled_templates/*
```

The galaxyproject.galaxy Ansible role can do the first step for you.

---
# Upgrading the galaxy repo

```console
$ git fetch
$ git checkout release_YY.MM
$ git pull --ff-only
```

---
# Diff samples

```console
$ git diff release_18.01..release_18.05 -- config/*.sample
```

Merge changes as desired/necessary.

---
# Upgrade virtualenv

```console
$ export GALAXY_CONFIG_FILE=/srv/galaxy/config/galaxy.yml
$ export GALAXY_VIRTUAL_ENV=/srv/galaxy/venv
$ . $GALAXY_VIRTUAL_ENV/bin/activate
$ pip install --upgrade pip setuptools
$ ./scripts/common_startup.sh
$ deactivate
```

---
class: left
# Client Artifacts

* Since 18.01, the `dev` and pre-release (frozen) Galaxy branches do not
contain client build artifacts (e.g. JavaScript bundles in `static/`).

* Since 18.09 not even the `release_*` branches include the client build. Instead Galaxy will check for local JavaScript changes and perform a build if neccessary (including the build dependency installation).

* You can always run `make client-production` to force the client build (the galaxyproject.galaxy Ansible role can do this for you).

[Documentation](https://github.com/galaxyproject/galaxy/blob/dev/client/README.md)
---
class: left
# Tool migrations?

Galaxy source tools -> Tool Shed

We haven't done any in a long time, but may do more.

Galaxy will notify you on the first startup it the upgrade includes migrations.

---
# Database migrations

1. **Backup** your database
   - [PostgreSQL backup docs](https://www.postgresql.org/docs/current/static/backup.html)
2. Run
   ```console
   $ sh manage_db.sh upgrade -c $GALAXY_CONFIG_FILE
   ```

The galaxyproject.postgresql Ansible role can configure PostgreSQL PITR backups and the galaxyproject.galaxy role can perform the database upgrades for you.

---
# Start Galaxy

* Monitor the log files
* Check `/api/version`
* Check that everything still works

---
# Distribute Galaxy

If you're using a compute cluster and not running from shared file system

---
class: left
# Downgrading

If for some reason you need to move back to an older release, the process is
similar, but the order is a bit different because the database downgrade needs
to be done while being on the newer branch:

```console
$ export GALAXY_CONFIG_FILE=/srv/galaxy/config/galaxy.yml
$ export GALAXY_VIRTUAL_ENV=/srv/galaxy/venv
$ sh manage_db.sh -c /srv/galaxy/config/galaxy.yml downgrade 140
$ find /srv/galaxy/server/lib -name '*.pyc' -delete
$ git fetch
$ git checkout release_18.01
$ git pull --ff-only
$ ./scripts/common_startup.sh
```

The database version of the release you want to downgrade to (version 135 for
the 18.01 release in the example above) can be found by looking at the last file in:
https://github.com/galaxyproject/galaxy/tree/release_18.01/lib/galaxy/model/migrate/versions/

---
### <i class="fas fa-key" aria-hidden="true"></i><span class="visually-hidden">keypoints</span> Key points

- Galaxy release notes contain important information about a new release.

- Backup of the database is essential when database migrations are necessary.

---

## Thank you!

This material is the result of a collaborative work. Thanks to the [Galaxy Training Network](https://wiki.galaxyproject.org/Teach/GTN) and all the contributors!

<a href="/archive/2020-12-01/hall-of-fame/martenson/" class="contributor-badge"><img src="https://avatars.githubusercontent.com/martenson" alt="Martin Čech">Martin Čech</a>, <a href="/archive/2020-12-01/hall-of-fame/afgane/" class="contributor-badge"><img src="https://avatars.githubusercontent.com/afgane" alt="Enis Afgan">Enis Afgan</a>, <a href="/archive/2020-12-01/hall-of-fame/nsoranzo/" class="contributor-badge"><img src="https://avatars.githubusercontent.com/nsoranzo" alt="Nicola Soranzo">Nicola Soranzo</a>

</div>

This material is licensed under the <a rel="license" href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>.