Deploying an Onyx Questionnaire

This details what is required to deploy our onyx questionnaire. The first few paragraphs outline some of the major prerequisites and some minor complications in deploying across development and production environments, and for additional deploymnets for external recruiting sites.

These notes are open for discussion or improvement.

The Onyx Questionnaire and the PMI Lookup

Onyx uses a web service to access the Patient Master Index (the PMI). This web service is provided by the pmi-lookup. The Onyx questionnaire is currently installed alongside the pmi-lookup; ie: within the same instance of tomcat.

This seems sensible as we have only one questionnaire at the moment, and we don't know what it would entail to run more than one questionnaire at the same time. These ideas will have to be worked out in time. For the moment, we are sticking to using one tomcat instance. This is almost certainly more secure as the Obiba interface for the web service is not encrypted at present.

There is a development and a production version of the pmi-lookup. The production version uses an SqlServer table function invocation in JDBC to retrieve demographic data. For testing Onyx in a situation where SqlServer is not available, the development version uses a MySql database.

Prerequisite Installs

• JDK 1.6.*
• Tomcat 6.*
• MySql 5.5.* but see below

Tomcat

Jeff can remember setting these on the original install (set in /etc/default/tomcat6):

JAVA_OPTS="-Xmx1024M -XX:MaxPermSize=256M"
TOMCAT6_SECURITY=no

But I also remember bumping up the memory incrementally to the maximum I could get away with on the production VM. So the above probably is smaller than the current production system settings.

MySql

In our use of Onyx, MySql is required for storing questionnaire data. For production (live or test), the database is more likely to be on a database server; ie: an entirely separate install. This is somewhat complicated by the development version of the pmi-lookup, which uses MySql.

These notes assume that MySql is installed somewhere.

Webapp Locations

The webapps will be located in a well known directory outside of the tomcat directory; for example: /usr/local/briccs-webapps
The actual directory should be customizable. Henceforth this will be $BRICCS_WEBAPPS

Deploying PMI Lookup Production Version

The version 1.0 artifact is located at ​http://mvn.briccs.org.uk/org/bru/briccs/briccs-pmi-lookup/production-1.0/briccs-pmi-lookup-production-1.0.war

The procedure should then follow this logical structure. The details/technique are open for discussion. Notes follow.

1. Unzip war file into $BRICCS_WEBAPPS/briccs-pmi-lookup-production-1.0
2. Locate config file at $BRICCS_WEBAPPS/briccs-pmi-lookup-production-1.0/WEB-INF/classes/pmi-lookup-config.properties
3. Edit the config file for database, user and password. There are appropriate templates in the config file.
4. Locate and edit log4j properties file at $BRICCS_WEBAPPS/briccs-pmi-lookup-production-1.0/WEB-INF/classes/log4j.properties
5. Place a context file for deployment within the tomcat tree: $CATALINA_HOME/webapps/patient-lookup.xml
6. Deploy within tomcat using manager commands of some sort.

PMI Context File

The context file can be used to limit access to local host, so rendering the webapp quite secure. It should read something like:

Context path="/patient-lookup" docBase="/usr/local/webapps/briccs-pmi-lookup-production-1.0">
    <Valve className="org.apache.catalina.valves.RemoteAddrValve" allow="127.0.0.1|192.168.2.4|0:0:0:0:0:0:0:1" deny=""/>
</Context>

The 192.168.2.4 should be changed (temporarilly?) to some suitably secure workstation for testing (eg: Nick's workstation)

Techniques

• The above is using a technique which is basically a variation of a manual technique using the tomcat manager. I'm agnostic on how we achieve this programatically. Dave to advise.
• Not keen on editing files. The deployment procedure can used what it likes to simplify the process.

Deploying PMI Lookup Development Version

The version 1.0 artifact is located at ​http://mvn.briccs.org.uk/org/bru/briccs/briccs-pmi-lookup/development-1.0/briccs-pmi-lookup-development-1.0.war

This version uses a MySql database. Suitable SQL for creating and inserting data can be found at:

• ​svn+ssh://svn.briccs.org.uk/var/local/briccs/svn/repo/onyx/tags/pmi-lookup-1.0/src/sql/DropAndCreate.sql
• ​svn+ssh://svn.briccs.org.uk/var/local/briccs/svn/repo/onyx/tags/pmi-lookup-1.0/src/sql/Inserts.sql

Once the database side has been dealt with, the procedure should be roughly the same as for a production version, with appropriate alterations as well to the context file:

1. Unzip war file into $BRICCS_WEBAPPS/briccs-pmi-lookup-development-1.0
2. Locate config file at $BRICCS_WEBAPPS/briccs-pmi-lookup-development-1.0/WEB-INF/classes/pmi-lookup-config.properties
3. Edit the config file for database, user and password. There are appropriate templates in the config file.
4. Locate and edit log4j properties file at $BRICCS_WEBAPPS/briccs-pmi-lookup-development-1.0/WEB-INF/classes/log4j.properties
5. Place a context file for deployment within the tomcat tree: $CATALINA_HOME/webapps/patient-lookup.xml
6. Deploy within tomcat using manager commands of some sort.

Raw Test of the PMI Lookup

Open a browser from a workstation allowed by the context file to use the pmi-lookup, even if only temporarily.
Use an appropriate url to retrieve a participant; eg: localhost:8080/patient-lookup/participant/S0000100/onyx.xml

Create a Database for the Onyx Data

Create a suitably named MySql database and a user with all privileges over the database. The Onyx webapp will do the rest.

Jeff remembers on the install of MySql that the my.cnf was edited...
Comment out the line 'bind 127.0.0.1'
I assume this is the case for a remote db server.

Deploying the Onyx Questionnaire

The briccs-onyx artifacts are located at ​http://mvn.briccs.org.uk/org/bru/briccs/briccs-onyx/$VERSION/briccs-onyx-$VERSION.war

As an example, the version 1.9.2 artifact is located at ​http://mvn.briccs.org.uk/org/bru/briccs/briccs-onyx/1.9.2/briccs-onyx-1.9.2.war

Unzip war file into $BRICCS_WEBAPPS/briccs-onyx-1.9.2

Distinguishing between Live and Test

There is a need at the user interface level to ensure a user realizes unambiguously that the system being used is either a live system or a test (ie: training system)...

See ​http://trac.briccs.org.uk/wiki/OnyxCode#DistinguishingBetweenaLiveandaTestsystemattheUserInterfaceLevel

Note from JL: I'm open on how to fold these files in. If required, I can generate two maven profiles (production and development) similar to the pmi-lookup. Then there would be two artifacts: one with development in the name and one with production in the name. Or something like it. It's just more work.

Edit onyx-config.properties

Locate config file at $BRICCS_WEBAPPS/briccs-onyx-1.9.2/WEBINF/config/onyx-config.properties

The following settings should be set appropriately to access the pmi-lookup:

# Must be true in order for the "Participant Registry" button to be present.
org.obiba.onyx.participant.registry.enabled=true
# The type of "Participant Registry". Values include "fixed" for development and "restful" for deployment.
org.obiba.onyx.participant.registry.type=restful
# The url use by the RestfulParticipantRegistry to lookup Participants from a remote service.
org.obiba.onyx.participant.registry.uriTemplate=http://localhost:8080/patient-lookup/participant/{identifier}/onyx.xml

The following settings should be set appropriately to access the database:

# MySQL
org.obiba.onyx.datasource.driver=com.mysql.jdbc.Driver
org.obiba.onyx.datasource.url=jdbc:mysql://localhost:3306/briccs01
org.obiba.onyx.datasource.username=someuser
org.obiba.onyx.datasource.password=********
org.obiba.onyx.datasource.dialect=org.hibernate.dialect.MySQL5InnoDBDialect
org.obiba.onyx.datasource.validationQuery=SELECT 1;
org.obiba.onyx.datasource.testOnBorrow=true

Edit Export Destinations File

Locate export destinations file at $BRICCS_WEBAPPS/briccs-onyx-1.9.2/WEBINF/config/export-destinations.xml
Comment out the encryption tag:

<!-- encrypt/ -->

We have done nothing with exporting data so far.

Edit Log4J File

Locate file at $BRICCS_WEBAPPS/briccs-onyx-1.9.2/WEBINF/classes/log4j.properties
Edit appropriately.

Question for Nick: Can you please send me (Jeff) or detail here the log4j properties file. I'm sure we've set up some rolling log files but I don't have access to refresh my memory. Actually, it would be good if you did the same for the pmi-lookup. I have a feeling the Obiba people had set up logging in such a way the system logs were rather polluted by low level program logging (eg: debug statements); and perhaps there is something here to get around this. Cannot remember the details.

First-run configuration

Once the above is completed,

Other issues

Automatic Restart

Can we please set tomcat to restart automatically on reboot? Same for MySql.

Once the war file has been unpacked, config settings and logos fixed appropriately, stop tomcat ('sudo service tomcat6 stop')alter the tomcat context file in /etc/tomcat6 to point to the correct directory, and then restart tomcat.

The new version of the questionnaire should then be running.