== 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.[[BR]] 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.[[BR]] 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. [[BR]] 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[[BR]] 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 1. Locate config file at $BRICCS_WEBAPPS/briccs-pmi-lookup-production-1.0/WEB-INF/classes/pmi-lookup-config.properties 1. Edit the config file for database, user and password. There are appropriate templates in the config file. 1. Locate and edit log4j properties file at $BRICCS_WEBAPPS/briccs-pmi-lookup-production-1.0/WEB-INF/classes/log4j.properties 1. Place a context file for deployment within the tomcat tree: $CATALINA_HOME/webapps/patient-lookup.xml 1. 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"> }}} 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 [[BR]] 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 1. Locate config file at $BRICCS_WEBAPPS/briccs-pmi-lookup-development-1.0/WEB-INF/classes/pmi-lookup-config.properties 1. Edit the config file for database, user and password. There are appropriate templates in the config file. 1. Locate and edit log4j properties file at $BRICCS_WEBAPPS/briccs-pmi-lookup-development-1.0/WEB-INF/classes/log4j.properties 1. Place a context file for deployment within the tomcat tree: $CATALINA_HOME/webapps/patient-lookup.xml 1. 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.[[BR]] 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...[[BR]] Comment out the line 'bind 127.0.0.1'[[BR]] 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 [[BR]] 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 [[BR]] 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)... [[BR]] 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 [[BR]] 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 [[BR]] Comment out the encryption tag: {{{ }}} 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 [[BR]] Edit appropriately.[[BR]] '''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.