Upgrade Guide

This document contains administrator instructions for upgrading specific versions of SODAR. It assumes the use of the SODAR Docker Compose environment.

General Upgrades

For most SODAR versions, the following procedure for upgrading can be followed:

Pull and check out the latest sodar-docker-compose release corresponding to the current SODAR server version.
Review and update your environment variables to match and/or support those recommended in the env.example file found in the current sodar-docker-compose release. Especially make sure SODAR_SERVER_VERSION is set to the latest version found in the sodar-server packages and that other image versions are as recommended in the example.
Pull and build the images.
Restart the Docker Compose network.

For SODAR releases where breaking changes require additional actions, release specific procedures are listed below.

All instructions assume you are running the previous major release of SODAR before performing the upgrade.

v1.3

Dependencies

This release requires at least the following versions of SODAR environment components:

sodar-docker-compose dev
irods-docker 4.3.4-2
davrods-docker 4.3.4_1.5.2-2

Environment Variables

The following changes have been made to environment variables:

Settings for django-axes have been added. For details on how to configure the app, see related SODAR Core documentation.
PROJECTROLES_LOCAL_USER_UPDATE added. Enabling this will allow local user accounts to update their user details.
ADMINALERTS_EMAIL_SENDING_DEFAULT added. Setting this False will disable admin alert email sending by default.

API Token Regeneration

Due to a breaking upgrade to django-rest-knox v5.x, existing API tokens no longer work and need to be regenerated. You should communicate this to your users. This is also mentioned in the Release Notes user upgrade guide.

v1.2

Dependencies

This release requires at least the following versions of SODAR environment components:

sodar-docker-compose 1.2-1
irods-docker 4.3.4-1
davrods-docker 4.3.4_1.5.2-1
Redis v8.x

Environment Variables

The following changes have been made to environment variables:

ENABLE_IRODS setting removed. If you need to set up a SODAR instance without iRODS and file access, disable the omics_irods and taskflowbackend backends along with other iRODS using apps.
LANDINGZONES_ZONE_MOVE_VERIFY added. Enabling this will result in asynchronous file integrity verification being triggered in the sample data after a successful landing zone move. This is True by default and can be disabled for e.g. performance reasons, or if no issues with move operations are to be expected with the file system used.
PROJECTROLES_ROLE_PAGINATION added. You can set this to control project member list pagination page size.
SHEETS_SYNC_ENABLED added. It is recommended to set this to False if the sample sheet synchronization feature between multiple SODAR instances is not to be used.

Study Table Cache Update

This release contains changes to sample sheet table header formatting in the UI. These changes are stored in the SODAR cache. If your instance has SHEETS_ENABLE_STUDY_TABLE_CACHE set True, you should run the syncstudytables management command to update existing sample sheets to the new formatting. Example:

$ ./manage.py syncstudytables

Known Issues

Due to a migration error in v1.2.0, landing zone operations for previously created zones may fail with the error Invalid coll_creation value: ZONE_COLLS_NONE. This will be fixed in v1.2.1. A workaround for v1.2.0 is to enter the following script into the Django shell:

from landingzones.models import LandingZone
    for zone in LandingZone.objects.filter(coll_creation='ZONE_COLLS_NONE'):
    zone.coll_creation = 'NONE'
    zone.save()

v1.1

Dependencies

This release requires at least the following versions of SODAR environment components:

sodar-docker-compose 1.1-1
irods-docker 4.3.3-2
davrods-docker 4.3.3_1.5.1-1

Warning

To deploy SODAR v1.1 on top of an existing deployment, you must first deploy SODAR v1.0. This means you can not upgrade directly from e.g. v0.15 straight to v1.1. Doing so risks a database migration failure. This is due to squashed migrations removed in v1.1.

Landing Zone Access Update

SODAR v1.1 adds project owners and delegates iRODS collection ownership to all landing zones in the project. To enable owner and delegate access on legacy zones created before v1.1, you need to run the syncmodifyapi management command. Example:

$ ./manage.py syncmodifyapi

v1.0

SODAR v1.0 contains breaking changes regarding upgrades to iRODS 4.3 and PostgreSQL >=12. When upgrading from a previous version, it is recommended to do a clean install.

This release requires at least the following versions of SODAR environment components:

sodar-docker-compose 1.0.0-1
irods-docker 4.3.3-2
davrods-docker 4.3.3_1.5.1-1
PostgreSQL >=12

Note

This release no longer supports iRODS <=4.2 and PostgreSQL <=11. Your iRODS and PostgreSQL servers must be updated for this release to work.

Warning

This upgrade may result in loss of data if performed incorrectly. Make sure your databases and other relevant files are backed up and follow the instructions carefully. If working in a production environment, it is recommended to take a snapshot of your host VM before proceeding.

If it is running, bring down the Docker Compose network except for the postgres container.

If not running, bring up the postgres container by itself.

Export and backup your sodar and ICAT databases.

SSH into the postgres container as the postgres user.
Example: pg_dump -cv DATABASE-NAME > /tmp/DATABASE-NAME_yyyy-mm-dd.sql
Make sure you export both databases.
Make sure you store the backups outside your Docker containers.
OPTIONAL: If you have made changes to iRODS config not present in the sodar-docker-compose repository, e.g. changing the iRODS rule files, also back up your iRODS config files at this point.
OPTIONAL: If you run an evaluation environment with the iRODS vault stored in a local volume and accessed directly via ICAT, also consider backing up your vault directory.

Pull the latest v1.0.0-* release of sodar-docker-compose.
Delete the iRODS configuration directory and PostgreSQL database volume.

WARNING: This will result in loss of data, so make sure you have successfully backed up everything before proceeding!
Example: sudo rm -rf config/irods/etc/ volumes/postgres

Update your .env file (or environment variables in your deployment scripts) to be compatible with the env.example file of the current sodar-docker-compose release.

NOTE: Make sure IRODS_PASS and IRODS_PASSWORD_SALT are set with the same values as in your previous installation. Otherwise iRODS will fail to run after re-importing old databases, as the service user is unable to connect to the ICAT server.

Run ./init.sh (or the corresponding command in your deployment scripts) to recreate directories.
Bring up the Docker Compose network.

If something fails in your SODAR or iRODS install, repeat steps 4-7.

Once SODAR and iRODS are successfully set up, bring down the Docker Compose network except for the postgres container.
Replace the sodar and ICAT databases in postgres with your database exports.

Example: psql DATABASE-NAME < /tmp/DATABASE-NAME_yyyy-mm-dd.sql

Restart the full Docker Compose network.

sodar-web will migrate your SODAR database on restart.
irods will use the previously backed up database on restart.

v0.15

To enable support for custom ISA-Tab templates, make sure to add isatemplates_backend to SODAR_ENABLED_BACKEND_PLUGINS in your environment variables.

v0.14

Upon deploying this release on an existing instance, admins must run the syncmodifyapi management command. This will update project user access in iRODS according to the role inheritance update introduced in SODAR Core v0.13.