In most cases, upgrading an existing instance of SHRINE is a relatively quick process. Exceptions to this rule include older versions of SHRINE that contained substantial changes to configuration files and other portions of the file structure. The instructions here specifically describe an upgrade path from SHRINE 1.20.1 to SHRINE 1.21.1. For instructions on upgrading to SHRINE 1.20.1, check the child pages underneath the "Archived Upgrade Instructions" section.

This guide makes the following assumptions of a current 1.20.1 user. Make sure all of these conditions are satisfied before proceeding:

• i2b2 1.7.05 or newer is installed and operational.
• SHRINE 1.20.1 is installed and operational. (along with Tomcat 7)

Shut Down SHRINE

Before starting the upgrade process, make sure SHRINE's Tomcat is not running. Leaving it running during this process can cause problems. Simply run the following command:

$ shrine_shutdown

If the above command is not found, try the following instead:

$ /opt/shrine/tomcat/bin/shutdown.sh

Create Backups

Now that SHRINE is stopped, it is a good idea to back up the current versions of the components we will be upgrading. The exact method for making this backups may vary, but these instructions will place the backups in a folder called /opt/shrine/upgrade-backups.

Start by creating a folder to contain these backups:

$ mkdir /opt/shrine/upgrade-backups

Remove the old .war files with this command:

$ rm /opt/shrine/tomcat/webapps/*.war

Next, move the current SHRINE webapp folder to the backup location:

$ mv /opt/shrine/tomcat/webapps/shrine /opt/shrine/upgrade-backups/shrine

Make sure to also back up other existing SHRINE components (shrine-proxy), just in case:

$ mv /opt/shrine/tomcat/webapps/shrine-proxy /opt/shrine/upgrade-backups/shrine-proxy

Make especially sure that the shrine-webclient/ folder is backed up. Later on, we will be restoring important webclient configuration files from this backup. If you choose not to make any backups, make sure to at least keep a copy of i2b2_config_data.js and js-i2b2/cells/SHRINE/cell_config_data.js!

$ mv /opt/shrine/tomcat/webapps/shrine-webclient /opt/shrine/upgrade-backups/shrine-webclient

Deploy New shrine.war

Next, we will retrieve the new SHRINE webapp from the HMS Sonatype Nexus server at http://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-war/. Navigate to the folder for 1.21.1. From there, download shrine-war-1.21.1.war to the webapps/ directory on the SHRINE server and rename it to shrine.war.

For example:

$ cd /opt/shrine/tomcat/webapps
$ wget --no-check-certificate https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-war/1.21.1/shrine-war-1.21.1.war -O shrine.war

Deploy New shrine-proxy.war

Like other SHRINE artifacts, the SHRINE proxy can be found on the HMS Sonatype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-proxy/. Navigate to the folder for 1.21.1. From there, download shrine-proxy-1.21.1.war to the webapps/ directory on the SHRINE server and rename it to shrine-proxy.war.

For example:

$ cd /opt/shrine/tomcat/webapps
$ wget --no-check-certificate https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-proxy/1.21.1/shrine-proxy-1.21.1.war -O shrine-proxy.war

Deploy New SHRINE Webclient

NOTE: Installation procedures for this component have changed after 1.19.x! Please be careful. Starting with 1.20.x, the SHRINE webclient is packaged as a zip file, and no longer requires a checkout from the old SHRINE SVN repository.

The SHRINE webclient can be found on the HMS Sonatype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-webclient/. Navigate to the folder for 1.21.1. From there, download shrine-webclient-1.21.1-dist.zip file to the webapps/ directory on the SHRINE server and rename it to shrine-webclient.zip. Then, unzip the shrine-webclient.zip file.

For example:

$ cd /opt/shrine/tomcat/webapps
$ wget --no-check-certificate https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-webclient/1.21.1/shrine-webclient-1.21.1-dist.zip -O shrine-webclient.zip
$ unzip shrine-webclient.zip

Restore Webclient Backups

After this, restore the previous i2b2_config_data.js and cell_config_data.js files from your backup and place them in the new shrine-webclient folder:

$ cp /opt/shrine/upgrade-backups/shrine-webclient/i2b2_config_data.js /opt/shrine/tomcat/webapps/shrine-webclient/i2b2_config_data.js

$ cp /opt/shrine/upgrade-backups/shrine-webclient/js-i2b2/cells/SHRINE/cell_config_data.js /opt/shrine/tomcat/webapps/shrine-webclient/js-i2b2/cells/SHRINE/cell_config_data.js

Deploy New SHRINE Dashboard

NOTE: This component is a working prototype, and simply mirrors information from the existing SHRINE Happy module in its current state. Additional functionality is coming in a future release.

Like other SHRINE artifacts, the SHRINE Dashboard can be found on the HMS Sonatype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/dashboard-war/. Navigate to the folder for 1.21.1. From there, download dashboard-war-1.20.1.war to the webapps/ directory on the SHRINE server and rename it to shrine-dashboard.war.

For example:

$ cd /opt/shrine/tomcat/webapps
$ wget --no-check-certificate https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/dashboard-war/1.21.1/dashboard-war-1.21.1.war -O shrine-dashboard.war

(Optional) For Users of Oracle or SQL Server

If you experience issues in getting the audit logging functionality working with Oracle or SQL Server, please try the instructions in this article written by a SHRINE developer: Using SHRINE Data Steward with Oracle or SQL Server (the instructions within also apply to the audit logging functionality).

This article contains links to alternative database drivers, as well as information on the necessary changes to make to shrine.xml and shrine.conf.

Due to the new query audit database functionality added in SHRINE 1.20.1, you will also need to modify shrine.conf. There are audit{} blocks that must be added to both the adapter{} and queryEntryPoint{} sections of shrine.conf. By default, these are configured to use MySQL, so users of MySQL do not need to add anything to their shrine.conf. However, users of Oracle or SQL Server for SHRINE must add them. See the below for an example:

shrine {
[...]
  queryEntryPoint {
    audit {
      database {
        slickProfileClassName="freeslick.driverNameHere$"
      }
    }
    [...]
  }
[...]
 
  adapter {
    audit {
      database {
        slickProfileClassName="freeslick.driverNameHere$"
      }
    }
    [...]
  }
[...]
}

Replace "freeslick.driverNameHere$" with the name of the driver you are using ("freeslick.OracleProfile$" for Oracle, and "freeslick.MSSQLServerProfile$" for SQL Server).

Update PRIVILEGED_USER Table Structure

The PRIVILEGED_USER table now allows a user's query threshold to be set to NULL to allow it to fall back to the current value in shrine.conf.Run the following queries on your SHRINE query history database:

alter table PRIVILEGED_USER modify column threshold int null;

Start SHRINE

The only thing left to do at this point is start SHRINE back up. Simply do the following:

$ shrine_startup

If the above command is not found, try the following instead:

$ /opt/shrine/tomcat/bin/startup.sh

Verify SHRINE Upgrade

After starting SHRINE up, verify that the upgrade was properly deployed by checking the SHRINE Dashboard. The exact address you will need to go to depends on your configuration, but the general format looks like the following:

https://your.shrine.host:6443/shrine-dashboard/client/index.html#/dashboard/diagnostics

It may take a few seconds for the page to load, but after it does load, log in with your SHRINE credentials (any user will do, regardless of role) and verify that the value for "SHRINE Version" is 1.20.1. If it is still displaying an old version, repeat the instructions in the "Deploy New shrine.war" section, restart SHRINE, and try again.