Versions Compared

Old Version 1

changes.mady.by.user Keith Dwyer

Saved on

compared with

New Version 2

changes.mady.by.user Keith Dwyer

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

If upgrading from SHRINE 1.17.x to SHRINE 1.19.x, you will need to make sure to run the database scripts listed in the "Schema Changes" section of of the 1.18.x article in  in addition to the instructions provided in this article.

...

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

...

Next, move the SHRINE webclient to that same backup location. Later on, we will be restoring i2b2_config_data.js from this backup. If you choose not to make any backups, make sure to at least keep a copy of of i2b2_config_data.js and js-i2b2/cells/SHRINE/cell_config_data.js!

...

Next, download the upgrade script from the SHRINE installer and run it.

$ wget https://open.med.harvard.edu/svn/shrine/releases/1.19.12/code/install/i2b2-1.7/shrine/upgrade_tomcat.sh
$ chmod +x upgrade_tomcat.sh
$ ./upgrade_tomcat.sh

...

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/. Choose the version that you are upgrading to (for example, 1.19.12) and navigate to that folder. From there, download the appropriate shrine-war-[VERSION].war file to the webapps directory on the SHRINE server and rename it to shrine.war.

...

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

Deploy

...

New shrine-proxy.war

Much like shrine.war, steward.war Like other SHRINE artifacts, the SHRINE proxy can be found on the HMS Sonatype Nexus server at httphttps://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/stewardshrine-proxy/. Navigate to the folder for 1.19.12. From there, download the appropriate steward-[VERSION]shrine-proxy-1.19.2.war file to the webapps directory on the SHRINE server and rename it to stewardshrine-proxy.war.

For example:

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

[Optional] Deploy New steward.war

Much like shrine.war, steward.war 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.19.2. From there, download the appropriate steward-[VERSION].war file to the webapps directory on the SHRINE server and rename it to steward.war.

For example:

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

Deploy New SHRINE Webclient

...

$ cd /opt/shrine/tomcat/webapps
$ svn export https://open.med.harvard.edu/svn/shrine/releases/1.1819.2/code/shrine-webclient/

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

...

$ 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

...

[Optional] Configure the SHRINE Data Steward

Note that a few of these steps can be automatically done by the install-steward-only.sh script available with the SHRINE installer.

...

The SHRINE Data Steward is typically backed by the i2b2 PM cell used by SHRINE. From the steward application's point of view, all users on the SHRINE project are considered Researchers. However, there is some additional work that has to be done to the i2b2 user list to accommodate the SHRINE Data Steward.

NOTE: install-steward-only.sh does  does NOT handle  handle this! The creation of i2b2 users/setting of user parameters must be done manually by an i2b2 administrator!

...

The Steward application requires set of user credentials that it will use to submit queries through to SHRINE. It is recommended that this be a dedicated user separate from any other account. Additionally, it will need to have the parameter "qep" defined (name: qep, value: true, type: text), which can be set in the Manage Users section of the i2b2 Admin Panel.

In shrine.conf, make sure there is a a shrineSteward block  block in the the queryEntryPoint section section, and that the the qepUserName and  and qepPassword properties  properties match the user with the qep parameter.

...

In Steward application deployments that require manual topic approval, a trusted user will have to be given permission to review proposed research topics and approve/reject them. To mark a user as such, add the "DataSteward" parameter (name: DataSteward, value: true, type: text) to that user in the Manage Users section of the i2b2 Admin Panel.

...

  1. Create a database (typically stored in MySQL alongside the existing shrine_query_history database, but this is just a suggestion). The installer by default calls it stewardDB.
  2. Grant a shrine/steward-specific user full access to this database. The installer by default uses the same credentials as it does for the SHRINE query history database, but you are welcome to (and encouraged to!) change this.
  3. Run the appropriate schema script included with the steward application
    1. For MySQL, this is https://open.med.harvard.edu/svn/shrine/releases/1.19.12/code/steward/src/main/sql/mysql.ddl
    2. For SQL Server, this is https://open.med.harvard.edu/svn/shrine/releases/1.19.12/code/steward/src/main/sql/sqlserver.ddl

steward.conf - Application config

...

  1. Start with a sample steward.conf from the installer: https://open.med.harvard.edu/svn/shrine/releases/1.19.12/code/install/i2b2-1.7/shrine/skel/steward.confsteward.conf
    1. If using the JDBC driver, make sure slickProfileClassName is set to "scala.slick.driver.JdbcDriver$" (mind the lowercase "dbc"!)
  2. Substitute the following variables with their appropriate value. (see common.rc and shrine.rc for reference, as well as as the listing of configuration variables in the installer)
    1. SHRINE_ADAPTER_I2B2_DOMAIN
    2. SHRINE_STEWARD_DB_NAME
    3. I2B2_PM_IP
    4. KEYSTORE_FILE
    5. KEYSTORE_PASSWORD
    6. KEYSTORE_ALIAS
  3. Save this file to /opt/shrine/tomcat/lib/steward.conf

An important setting in steward.conf which should be manually set by a site administrator is createTopicsMode. By default, this is set to "Pending", which means that topic requests submitted in the Data Steward application will have to be manually approved by a user with DataSteward privileges. The potential values for for createTopicsMode are are:

  • Pending: Topic requests must be submitted, and a user with the DataSteward parameter set for them in the i2b2 PM cell must log in and approve them manually before queries can be executed under that topic.
  • Approved: Topic requests must be submitted, but no manual approval is necessary. All topics submitted are automatically approved, and researchers can immediately begin executing queries for that topic.
  • TopicsIgnoredJustLog: No topic requests are necessary, the Data Steward application simply intercepts queries for recordkeeping and analysis. If using this mode, ensure

...

  • the isSHRINE

...

  •  property in shrine-webclient/i2b2_config_data.js is either not present or set

...

  • to false

steward.xml - Tomcat context definition

...

  1. Start with a sample steward.xml from the installer: https://open.med.harvard.edu/svn/shrine/releases/1.19.12/code/install/i2b2-1.7/shrine/skel/steward.xml
  2. Substitute the following variables with their appropriate value. (see common.rc and shrine.rc for reference, as well as the listing of configuration variables in the installer)
    1. SHRINE_STEWARD_MYSQL_USER
    2. SHRINE_STEWARD_MYSQL_PASSWORD
    3. SHRINE_STEWARD_MYSQL_HOST
    4. SHRINE_STEWARD_DB_NAME
  3. Save this file to /opt/shrine/tomcat/conf/Catalina/localhost/steward.confxml

SHRINE Webclient

NOTE: install-steward-only.sh does NOT handle this step!

In webapps/shrine-webclient/js-i2b2/cells/SHRINE/cell_config_data.js, make sure newTopicURL is and readApprovedURL are set to something like the following:

    newTopicURL: "https://your.hostname.here:

...

    newTopicURL: 6443/steward/client/index.html#/topics",
    readApprovedURL:"https://your.hostname.here:6443/stewardshrine/clientrest/index.html#i2b2/topicsrequest"

If If createTopicsMode in  in steward.conf is set to either "Approved" or "Pending", then make the following change in webapps/shrine-webclient/i2b2_config_data.js:

...

The above may already be present in i2b2_config_data.js, but commented out. (there may be a /* on the previous line) If so, uncomment it. If If isSHRINE is  is not already present, add it to the main entry in in lstDomains.

shrine.conf Changes

...

If using the SHRINE Data Steward, you will need to change the authorizationType value and add the following shrineSteward block to the queryEntryPoint block of shrine.conf:

queryEntryPoint {
  ...
  authorizationType = "shrine-steward"

  shrineSteward {
    qepUserName = "qep" // name of user the steward will submit queries as
    qepPassword = "trustme"
    stewardBaseUrl = "https://your.hostname.here:6443" // typically hostname+port of Tomcat server running steward.war
  }

  ...
}

...

It may take a few seconds for the page to load, but after it does load, verify that the value for <shrineVersion> matches the version that was just deployed. If it is still displaying an old version, repeat steps 1 and 4 to redeploy the shrine.war file and start SHRINE again. Example output from this report for SHRINE 1.19.1 2 can be seen below:

<versionInfo>
  <shrineVersion>1.19.1<2</shrineVersion>
  <ontologyVersion>UNKNOWN</ontologyVersion>
  <adapterMappingsVersion>Unknown</adapterMappingsVersion>
  <scmRevision>(not available)</scmRevision>
  <scmBranch>UNKNOWN_BRANCH</scmBranch>
  <buildDate>2015-06-0430 0918:2103:05<57</buildDate>
</versionInfo>