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 to SHRINE 1.22. For instructions on upgrading to SHRINE 1.20, check the child pages underneath the "Archived Upgrade Instructions" section.

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

i2b2 1.7.08a or newer is installed and operational.
SHRINE 1.20 or 1.21 is installed and operational.
The SHRINE Data Steward included with 1.19.2 has been installed and configured properly.

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 the other existing SHRINE components (shrine-proxy and steward), just in case:

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

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

Upgrade to JDK 8 and Tomcat 8

SHRINE 1.22 was tested only with JDK 8 and Tomcat 8. Future versions of SHRINE will require JDK 8 and Tomcat 8.

Modify Tomcat

With JDK 8, tomcat no longer needs a MaxPermSize set to run SHRINE. You may remove the part of setenv.sh that set:

setenv.sh contents

export CATALINA_OPTS=" -XX:MaxPermSize=256m -Dakka.daemonic=on "

or the part of setenv.bat that set:

setenv.bat contents

set CATALINA_OPTS=-XX:MaxPermSize=256m -Dakka.daemonic=on

Deploy New shrine.war

Next, we will retrieve the new SHRINE webapp from the HMS Sonatype Nexus server athttps://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-war/. Navigate to the folder for 1.22.4. From there, download shrine-war-1.22.4.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 http://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/shrine-war/1.22.4/shrine-war-1.22.4.war -O shrine.war

Deploy New steward.war

Much like shrine.war, the SHRINE Data Steward can be found on the HMS Sonatype Nexus server at http://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/steward/. Navigate to the folder for 1.22.4. From there, download steward-1.22.4.war to the webapps/ directory on the SHRINE server and rename it to steward.war.

For example:

$ cd /opt/shrine/tomcat/webapps
$ wget --no-check-certificate https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/steward/1.22.4/steward-1.22.4 -O steward.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.22.4. From there, download shrine-proxy-1.22.4.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.22.4/shrine-proxy-1.22.4.war -O shrine-proxy.war

Deploy New SHRINE Webclient

The SHRINE webclient can now 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.22.4. From there, download shrine-webclient-1.20.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.22.4/shrine-webclient-1.22.4-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

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.22.4. From there, download dashboard-war-1.22.4.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.22.4/dashboard-war-1.22.4 -O shrine-dashboard.war

Deploy New SHRINE Node Metadata Service

Like other SHRINE artifacts, the SHRINE Node Metadata Service can be found on the HMS Sonatype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/meta-war/. Navigate to the folder for 1.22.4. From there, download meta-war-1.22.4.war to the webapps/ directory on the SHRINE server and rename it to shrine-meta.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.22.4/dashboard-war-1.22.4 -O shrine-dashboard.war

(Optional) For Users of Oracle or SQL Server

If you experience issues in getting the SHRINE Data Steward (or the new 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

This article contains links to alternative database drivers, as well as links to alternative database scripts for creating tables for the SHRINE Data Steward. It also includes information on the necessary changes to make to shrine.xml, steward.xml, and shrine.conf.

shrine.conf includes several instances of slickProfileClassName. By default, these are configured to use MySQL. 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).

Database Changes

SHRINE 1.22 adds a table of problems to each SHRINE node, to help diagnose problems observed on that node.

Add a table named "problems" to the shrine_query_history database

/* Working tables in shrine_query_history */
create table `problems` (`id` BIGINT NOT NULL AUTO_INCREMENT PRIMARY KEY,`codec` TEXT NOT NULL,`stampText` TEXT NOT NULL,`summary` TEXT NOT NULL,`description` TEXT NOT NULL,`detailsXml` TEXT NOT NULL,`epoch` BIGINT NOT NULL);
create index `idx_epoch` on `problems` (`epoch`)

Expand the limit on the number of characters in a flag message to the database's limit for unbound text

alter table SHRINE_QUERY change flag_message flag_message text;

Change the PRIVILEGED_USER table's threshold column to accept nulls (and use the default threshold after resetting for lockout).

alter table PRIVILEGED_USER change threshold threshold int null;

TODO start here, hub and qep and general tables

Create Query Audit Databases

SHRINE 1.20.1 adds query audit databases, which will need to be created in order for SHRINE 1.20.1 to function.

Create a database named adapterAuditDB on the same database server used for storing SHRINE query history.
Download and run the schema creation script for the adapterAuditDB database, available here: https://open.med.harvard.edu/stash/projects/SHRINE/repos/shrine/browse/adapter/adapter-service/src/main/sql/mysql.ddl?at=tags/1.20.1&raw
1. Other schema creation scripts can be found in the same folder: https://open.med.harvard.edu/stash/projects/SHRINE/repos/shrine/browse/adapter/adapter-service/src/main/sql/?at=tags/1.20.1
Create a database named qepAuditDB on the same database server used for storing SHRINE query history.
Download and run the schema creation script for the qepAuditDB database, available here: https://open.med.harvard.edu/stash/projects/SHRINE/repos/shrine/browse/qep/service/src/main/sql/mysql.ddl?at=tags/1.20.1&raw
1. Other schema creation scripts can be found in the same folder: https://open.med.harvard.edu/stash/projects/SHRINE/repos/shrine/browse/qep/service/src/main/sql?at=tags/1.20.1
In tomcat/conf/Catalina/localhost/shrine.xml, add two new <Resource> elements for each of these new databases. You can copy and paste the lines used for shrine_query_history Resource, making sure that both the "shrineDB" part of the name attribute and the "shrine_query_history" part of the url attribute both change to "adapterAuditDB" for the first copy and "qepAuditDB" for the second copy.

Update ERROR_RESULT Table Structure

In order to accommodate improvements made to error reporting in the SHRINE webclient, additional columns have been added to the ERROR_RESULT table in the shrine_query_history database. Run the following queries on your SHRINE query history database:

mysql -u shrine -p -D shrine_query_history

alter table ERROR_RESULT add column CODEC varchar(256) not null default "Pre-1.20 Error";
alter table ERROR_RESULT add column STAMP varchar(256) not null default "Unknown time and machine";
alter table ERROR_RESULT add column SUMMARY text not null;
alter table ERROR_RESULT add column PROBLEM_DESCRIPTION text not null;
alter table ERROR_RESULT add column DETAILS text not null;

shrine.conf Changes

(Optional) New Property - create

The hub{}, adapter{}, and queryEntryPoint{} components in shrine.conf have an additional (optional) boolean property named "create". This will enable or disable creation of that component. For example, a site that serves solely as a data source (no webclient, no querying users at their site) could disable the hub{} and queryEntryPoint{} components.

In SHRINE 1.20.1, the default value for this is true, but this is subject to change in a future release.

hub {
  ...
  create = false // this is solely an example, not a mandatory change.
  ...
}

steward.conf Changes

Change slickProfileClassName

Due to an underlying library upgrade, the names of the database drivers used for this variable have changed. If your current value for slickProfileClassName starts with "scala.", remove "scala." from it. For example, change this:

slickProfileClassName = "scala.slick.driver.MySQLDriver$"

To this:

slickProfileClassName = "slick.driver.MySQLDriver$"

Wrapper for usersource block

Surround the usersource{} block with a new block called authenticate{}. For example:

  authenticate {
    usersource {
      domain = "i2b2demo"
    }
  }

(Optional) Increase pmEndpoint timeout

If you experience issues with the SHRINE webclient occasionally failing to retrieve a list of approved topics and are certain the SHRINE Data Steward application is otherwise functioning properly, try increasing the timeout for the SHRINE Data Steward's interactions with the i2b2 PM cell. By default, the SHRINE Data Steward will only wait 1 second for a response from i2b2. To increase this limit, add the following inside the pmEndpoint{} block:

  pmEndpoint {
    [...]
    timeout {
      seconds = 10
    }
  }

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.

shrine {
  pmEndpoint {
    //URL for the PM Service, used to authenticate users
    url = "http://our.site.edu/i2b2/services/PMService/getServices"
  }

  authenticate {
    usersource {
      domain = "i2b2demo"
    }
  }

  keystore {
    file = "/opt/shrine/shrine.keystore"
    password = "PASSWORD"
    privateKeyAlias = "our.site.edu"
  }
}

Page tree

Upgrading SHRINE to 1.22

Shut Down SHRINE

Create Backups

Upgrade to JDK 8 and Tomcat 8

Modify Tomcat

Deploy New steward.war

Deploy New shrine-proxy.war

Deploy New SHRINE Webclient

Deploy New SHRINE Dashboard

Deploy New SHRINE Node Metadata Service

(Optional) For Users of Oracle or SQL Server

Database Changes

Create Query Audit Databases

Update ERROR_RESULT Table Structure

shrine.conf Changes

(Optional) New Property - create

steward.conf Changes

Change slickProfileClassName

Wrapper for usersource block

(Optional) Increase pmEndpoint timeout

Start SHRINE

Verify SHRINE Upgrade