Date: Thu, 28 Mar 2024 07:55:54 -0400 (EDT) Message-ID: <718088993.740.1711626954543@prodopencatalystconfluence.catalyst> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_739_1276051251.1711626954540" ------=_Part_739_1276051251.1711626954540 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
This guide makes the following assumptions of ACT network member= s. Make sure all of these conditions are satisfied before proceeding:
These instructions are based on the instructions in the general Upgrading SHRINE to = 1.22.8 (from 1.20-1.21) article. You will need to follow all the i= nstructions provided here in order to upgrade to SHRINE 1.20.1 and to prope= rly configure new SHRINE features.
Before starting the upgrade process, make sure SHRINE's Tomcat is not ru= nning. Leaving it running during this process can cause problems. Simply ru= n the following command:
$ shrine_shutdown
If the above command is not found, try the following instead:
$ /opt/shrine/tomcat/bin/shutdown.sh
Now that SHRINE is stopped, it is a good idea to back up the current ver= sions of the components we will be upgrading. The exact method for making t= his backups may vary, but these instructions will place the backups in a fo= lder 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/shr= ine
Make sure to also back up the other existing SHRINE components (shrine-p= roxy and steward), just in case:
$ mv /opt/shrine/tomcat/webapps/shrine-proxy /opt/shrine/upgrade-backu= ps/shrine-proxy
$ mv /opt/shrine/tomcat/webapps/steward /opt/shrine/upgr= ade-backups/steward
Make especially sure that the shrine-webclient/ folder is backed up. Later on, we wil= l 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&n= bsp;i2b2_config_data.js and = js-i2b2/cells/SHRINE/cell_config_data.js!
$ mv /opt/shrine/tomcat/webapps/shrine-webclient /opt/shrine/upgrade-b= ackups/shrine-webclient
You will need to create a file called setenv.sh&nb= sp;in Tomcat's bin/ folder to increase the PermG= en size given to Tomcat. This will prevent OutOfMemoryError messages caused= by one of the underlying application libraries. Addi= tionally, you will need to change a setting used by that same underlying li= brary so Tomcat will properly shut down. Make sure this file is owned by th= e same user that runs SHRINE, and make sure it is executable:
$ cd /o= pt/shrine/tomcat/bin $ vi setenv.sh $ sudo chown shrine:shrine setenv.sh $ sudo chmod 755 setenv.sh
The contents of setenv.sh should look like th= is:
export = CATALINA_OPTS=3D" -XX:MaxPermSize=3D256m -Dakka.daemonic=3Don "
If using Windows, the file should be named setenv.bat instead, and the contents should look something like this:
s= et CATALINA_OPTS=3D-XX:MaxPermSize=3D256m -Dakka.daemonic=3Don
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.20.1. From there, download shrine-war-1.20.1.war to the webapps/ direc=
tory 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.20.1/shrine-war-1.20.1.war -O shrine.war
NOTE: The previous bug with the SHRINE Data Stewar= d turning all usernames into lowercase has been fixed. Any i2b2 usernames t= hat use both uppercase and lowercase letters will now be able to use the SH= RINE Data Steward properly. However, for the sake of consistency, please co= ntinue using all lowercase letters in your usernames if they were already c= hanged.
Much like shrine.war, the SHRINE Data Steward can be found on the HMS So= natype Nexus server at http://repo.open.med.harvard.edu/nexus/content/groups/public/= net/shrine/steward/. Navigate to the folder for 1.20.1. From there, dow= nload steward-1.20.1.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.20.1/steward-1.20.1.war -O steward.war
Like other SHRINE artifacts, the SHRINE proxy can be found on the HMS So= natype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/pu= blic/net/shrine/shrine-proxy/. Navigate to the folder for 1.20.1. From = there, download shrine-proxy-1.20.1.war to the web= apps/ directory on the SHRINE server and rename it to shri= ne-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.20.1/shrine-proxy-1.20.1.war -O shrine= -proxy.war
NOTE: Installation procedures for this component h= ave changed! Please be careful. The SHRINE webclient is now packaged as a z= ip file, and no longer requires a checkout from the (no-longer-used) SHRINE= SVN repository.
The SHRINE webclient can now be found on the HMS Sonatype Nexus ser= ver at https://repo.open.med.harvard.edu/nexus/content/groups/public/net/shrine/s= hrine-webclient/. Navigate to the folder for 1.20.1. From there, downlo= ad shrine-webclient-1.20.1-dist.zip file to the we= bapps/ directory on the SHRINE server and rename it to shr= ine-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.20.1/shrine-webclient-1.20.1-d= ist.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&= nbsp;/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-i2= b2/cells/SHRINE/cell_config_data.js
NOTE: This component is a working prot= otype, and simply mirrors information from the existing SHRINE Happy module= in its current state. Additional functionality is coming in a future relea= se.
Like other SHRINE artifacts, the SHRINE proxy can be found on the HMS So= natype Nexus server at https://repo.open.med.harvard.edu/nexus/content/groups/p= ublic/net/shrine/dashboard-war/. Navigate to the folder for 1.20.1. Fro= m there, download dashboard-war-1.20.1.war to the = webapps/ directory on the SHRINE server and rename it to s= hrine-dashboard.war.
For example:
$ cd /opt/shrine/tomcat/webapps
$ wget --no-check-certificate = https://repo.open.med.harvard.edu/nexus/content/group= s/public/net/shrine/dashboard-war/1.20.1/dashboard-war-1.20.1.war -O sh= rine-dashboard.war
A new .conf file is required for the new SHRINE Dashboard c= omponent. Its contents are relatively simple, and can be mostly copied from= an existing steward.conf.
dashboard.conf should look something like = this:
shrine { pmEndpoint { //URL for the PM Service, used to authenticate users url =3D "http://our.site.edu/i2b2/services/PMService/getServi= ces" } authenticate { usersource { domain =3D "i2b2demo" } } keystore { file =3D "/opt/shrine/shrine.keystore" password =3D "PASSWORD" privateKeyAlias =3D "our.site.edu" } }
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 Da=
ta Steward. It also includes information on the necessary changes to make t=
o shrine.xml, steward.xml,
Also note that due to the new query audit database functionality added i= n 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{} sec= tions of shrine.conf. By default, these are configured to use MySQL, so use= rs of MySQL do not need to add anything to their shrine.conf. However, user= s of Oracle or SQL Server for SHRINE must add them. See the below for an ex= ample:
shrine { [...] queryEntryPoint { audit { database { slickProfileClassName=3D"freeslick.driverNameHere$" } } [...] } [...] =20 adapter { audit { database { slickProfileClassName=3D"freeslick.driverNameHere$" } } [...] } [...] }
Replace "freeslick.driverNameHere$" with the name of the driver you are = using ("freeslick.OracleProfile$" for Oracle, and "freeslick.MSSQLServerPro= file$" for SQL Server).
SHRINE 1.20.1 adds query audit databases, which will need t= o be created in order for SHRINE 1.20.1 to function.
In order to accommodate improvements made to error reporting in the SHRI= NE webclient, additional columns have been added to the ERROR_RESULT table = in the shrine_query_history database. Run the following qu= eries on your SHRINE query history database:
alter ta= ble ERROR_RESULT add column CODEC varchar(256) not null default "Pre-1.20 E= rror"; alter table ERROR_RESULT add column STAMP varchar(256) not null default "Un= known 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;
In the adapter block of shrine.conf, change adapterLockoutAttemptsT= hreshold to 6:
adapter {
...
adapterLockoutAttemptsThreshold =3D 6
...=
}
Due to an underlying library upgrade, the names of the database drivers = used for this variable have changed. If your current value for slickProfile= ClassName starts with "scala.", remove "scala." from it. For example, chang= e this:
slickProfileClassName =3D "scala.slick.driver.MySQLDriver= $"
To this:
slickProfileClassName =3D "slick.driver.MySQLDriver$"Wrapper fo= r usersource block
Surround the usersource{} block with a new block called authenticate{}. = Make sure this block is outside of the steward{} block. For example:= p>
shrine { steward { ... } authenticate { usersource { domain =3D "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 Stewa= rd application is otherwise functioning properly, try increasing the timeou= t for the SHRINE Data Steward's interactions with the i2b2 PM cell. By defa= ult, the SHRINE Data Steward will only wait 1 second for a response from i2= b2. To increase this limit, add the following inside the pmEndpoint{} block= :
pmEndpoint { [...] timeout { seconds =3D 10 } }Start SHRINE
The only thing left to do at this point is start SHRINE back up. Simply = do the following:
$ shrine_startupIf the above command is not found, try the following instead:
$ /opt/shrine/tomcat/bin/startup.shVerify SHRINE Up= grade
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 follow= ing:
https://your.shrine.host:6443/shrine-dashboard/client/index.html#/dash= board/diagnosticsIt 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 di= splaying an old version, repeat the instructions in the "Deploy New= shrine.war" section, restart SHRINE, and try again.