== 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.[[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     

=== !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">
    <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 [[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.