...

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:

...

$ /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.

...

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

Modify Tomcat

You will need to create a file called setenv.sh in Tomcat's bin/ folder to increase the PermGen size given to it. This will prevent OutOfMemoryError messages caused by one of the underlying application libraries. Make sure this file is owned by the same user that runs SHRINE, and make sure it is executable:

...

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

Deploy New steward.war

NOTE: The previous bug with the SHRINE Data Steward turning all usernames into lowercase has been fixed. Any i2b2 usernames that use both uppercase and lowercase letters will now be able to use the SHRINE Data Steward properly. However, for the sake of consistency, please continue using all lowercase letters in your usernames if they were already changed.

...

$ cd /opt/shrine/tomcat/webapps
$ wget --no-check-certificate https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/steward/1.20.1/steward-1.20.1.war -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.20.1. From there, download shrine-proxy-1.20.1.war to the webapps/ directory on the SHRINE server and rename it to shrine-proxy.war.

...

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

Deploy New SHRINE Webclient

NOTE: Installation procedures for this component have changed! Please be careful. The SHRINE webclient is now packaged as a zip file, and no longer requires a checkout from the (no-longer-used) SHRINE SVN repository.

...

$ 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.

...

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

Create dashboard.conf File

A new .conf file is required for the new SHRINE Dashboard component. Its contents are relatively simple, and can be mostly copied from an existing steward.conf.

...

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"
  }
}

(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

...

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

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.

1. Create a database named adapterAuditDB on the same database server used for storing SHRINE query history.
2. 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
3. Create a database named qepAuditDB on the same database server used for storing SHRINE query history.
4. 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
5. 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:

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.

...

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 = "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:

...

$ /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:

...