MyOscar2 on Java 7 Install

The following instructions will install Tomcat 7 to your new stand alone Ubuntu 12_04 LTS MyOscar installation

Now stop the tomcat7 service

Run the following command in your console to edit JAVA_HOME in the default tomcat7 start-up configuration file:

Change the JAVA_HOME option to the following:

Save the file and you are done. Tomcat will now start using the Oracle JDK instead of OpenJDK when you start the tomcat7 service

Check to ensure that Tomcat is running and you are running on the Oracle JDK

You cannot use apt-get to install Tomcat 7 on a machine where you have Tomcat 6 installed, it will fail.  And yet Tomcat 6 is necessary to run Oscar12_1.  Thus a manual installation is required. 

cd /var/lib
sudo wget http://apache.mirror.rafal.ca/tomcat/tomcat-7/v7.0.39/bin/apache-tomcat-7.0.39.tar.gz
sudo tar xvzf apache-tomcat-7.0.39.tar.gz

sudo ln -s /var/lib/apache-tomcat-7.0.39 ./tomcat7

sudo $JAVA_HOME/bin/keytool -genkey -alias tomcat -validity 3650 -keyalg RSA -keystore /var/lib/tomcat7/.keystore -keypass liyi -storepass liyi

Now reference the generated keystore in the tomcat configuration file. Activate those connectors in server.xml specification taking care that you don't conflict with another services that might be using those ports.

   <Connector port="8090" protocol="HTTP/1.1"
               connectionTimeout="20000"
               redirectPort="8091" />  
   <Connector port="8091" protocol="HTTP/1.1" 
               SSLEnabled="true"
               maxThreads="200" 
               scheme="https" 
               secure="true" 
               enableLookups="false" 
               disableUploadTimeout="true" 
               clientAuth="false"  
               sslProtocol="TLS" 
               keystoreFile="/var/lib/tomcat7/.keystore"
               keystorePass="liyi"   />

The source is in Git.  Follow the IDE Oscar install instructions, clone the source oscar_clinic_component, myoscar_server2 and oscar_client2 projects.  Then change to each projects directory and compile each with maven and copy the resultant to the tomcat webapps directory. 

Most of these components  are built against java 7.   Oscar_clinic_component is different and handled separately below. The following are not requirements but are versions that work for compiling

mvn package -Dmaven.test.skip=true
cd target
sudo mv *-SNAPSHOT.war /var/lib/tomcat7/webapps/myoscar_server.war

$ wget http://sourceforge.net/projects/myoscar/files/myoscar2/myoscar_server-2013-08-13.war
$ wget http://sourceforge.net/projects/myoscar/files/myoscar2/myoscar_client-2013-08-13.war
$ sudo cp myoscar_server-2013-08-13.war $CATALINA_BASE/myoscar_server.war
$ sudo cp myoscar_client-2013-08-13.war $CATALINA_BASE/myoscar.war

OPTIONAL  If in development environment it may be useful to run the tests to check the build, to do that you need to setup a dbuser user with the dbpasswordf password for MySQL prior to compiling .  At the MySQL prompt type

mysql>CREATE USER 'dbuser'@'localhost' IDENTIFIED BY 'dbpassword';
mysql>GRANT ALL ON *.* to 'dbuser'@'localhost' IDENTIFIED BY 'dbpassword';

Note that running the tests creates a myoscar_server database that will need to be dropped prior to initializing with a blank database or test data.  For security reasons in production use remember to DROP USER the dbuser user or change the password to one that is not published after you are done with building.

OPTIONAL  For debugging purposes it may be useful to setup the tomcat manager application by editing tomcat-users.xml

sudo nano /var/lib/tomcat7/conf/tomcat-users.xml

and add the following to the <tomcat-users> section (provide your own username and password)

sudo nano $CATALINA_BASE/myoscar_server/WEB-INF/classes/config.xml

<?xml version="1.0" encoding="UTF-8"?>
<server>
	<database>
		<user>MySQLuser</user>
		<password>MySQLpassword</password>
		<url_prefix>jdbc:mysql://127.0.0.1:3306/</url_prefix>
		<schema>myoscar_server2</schema>
		<driver>com.mysql.jdbc.Driver</driver>
	</database>
	<smtp>
		<host>smpt.gmail.com</host>
		<ssl_port>443</ssl_port>
		<user>user</user>
		<password>userpassword</password>
	</smtp>
</server>

Start Tomcat 7

cd /var/local/tomcat7/bin
sudo ./startup.sh

After installation and loading Tomcat you should go to http://localhost:8090/myoscar_server/admin/install.jsp to initialize the database. 

You will be warned if a database already exists (you will have to drop the schema manually if you want to reload a blank database)

Encryption is optional.  Probably you should NOT encrypt the database if you followed the instructions to encrypt the entire Ubuntu disk as suggested in the Oscar installation instructions.  Click the button.

 Wait a while and you will be given a screen with the following message:

MyOscar Server Admin

Then test that the connection works on http://localhost:8090/myoscar_server/ws

 Finally test that the connection also works on what you supplied for  "https_endpoint_url_base" in the XML file https://localhost:8091/myoscar_server/ws  as its this connection that the MyOscar client uses.  (you will see the same screen if it works)

MyOscar Client Configuration

sudo vi $CATALINA_BASE/myoscar/WEB-INF/classes/config.xml

<?xml version="1.0" encoding="UTF-8"?>
<server>
        <smtp>
                <host>smtp.gmail.com</host>
                <ssl_port>465</ssl_port>
                <user>user@gmail.com</user>
                <password>userpassword</password>
       </smtp>
       <myoscar_client>
                <!-- 
                <myoscar_server_base_url>http://127.0.0.1:8090/myoscar_server</myoscar_server_base_url>
                 -->
                <myoscar_server_base_url>https://127.0.0.1:8091/myoscar_server</myoscar_server_base_url>
                <contact_us_recipient_email_addresses>example@domain</contact_us_recipient_email_addresses>
                <contact_us_from_email_address>notifier@example.com</contact_us_from_email_address>

       </myoscar_client>
</server>

cd /var/local/tomcat7/bin
sudo ./shutdown.sh
sudo ./startup.sh

Test your login to the client http://127.0.0.1:8090/myoscar

sudo vi /var/local/tomcat7/bin/setenv.sh

JAVA_OPTS="${JAVA_OPTS} -Dmyoscar_client_config=client_override.xml"

Its optional but if you want appointment scheduling we have to configure that too.   You will need to have setup Oscar with the schedule templates for the providers working schedule. This means you must also have created appointment types and time codes for the schedule, also make sure you setup the holiday days properly in oscar.

First clone the code (you need an account on oscartools.org to download)

Unlike the other components  this is built against java 6.  You can check what you are using by checking version information for maven

peter@phc-14:~/git$ cd oscar_clinic_component/
peter@phc-14:~/git/oscar_clinic_component$ mvn -Dmaven.test.skip=true clean package

Second deploy/copy the war file into the Tomcat 7 servlet container like any standard war.

Edit config.xml, and preferably externalise the changes as am portal_override.xml file. The 2 most important settings would be the oscar web services settings and the myoscar server web services settings, they need to be correct for this to connect to them.

Note that the actual appointment settings have been externalised as well to clinicBooking.xml which might look like the following.  Note that the appointment_code is a comma separated subset of codes found in Oscar's database oscar_12_1.scheduletemplatecode.code.  Similarly the appointment_type id's and names are taken from oscar_12_1.appointmentType

For manually installed tomcat 7 it will be like the following

cd /var/lib/tomcat7/bin
sudo ./shutdown.sh
sudo ./startup.sh

Optional bit

TIP: If you are going to be re-installing the war, rather than redoing this every time, copy this modified configuration outside the application itself and reference it when you start tomcat.  To do that pass a system parameter of "-Doscar_patient_portal_config=override.xml" where override.xml is an xml config file which trumps the default one.  One way of doing this is to put this information into the bin directory of Tomcat7 in setenv.sh which gets run when you start Tomcat7 with 

sudo vi /var/local/tomcat7/bin/setenv.sh

You can specify a number of options here but for this purpose we want to add a parameter to JAVA_OPTS

JAVA_OPTS="${JAVA_OPTS} -oscar_patient_portal_config=portal_override.xml"

Oscar Configuration for MyOscar2

MY_OSCAR=yes
MY_OSCAR_EXCHANGE_INTERVAL = 5
ModuleNames=Indivo
# this is the link for 'view PHR record' in Oscar's Master File for the myOscar client
# If anyone needs to use Oscar off site it should be set to the myoscar client WAN IP and NOT the LAN 
myOSCAR.url = https://WAN_IP:8091/myoscar/
# this is the Oscar server to myoscar_server connection so should be routed locally
# currently if you have a self signed certificate, you may have to run it as http
myoscar_server_base_url=http://10.69.241.1:8090/myoscar_server/ws

# cxf web services set to your LAN ip of your OSCAR instance
https_endpint_url_base=http://192.168.1.1:8080/Oscar12_1/ws 

If your Oscar database is not configured with MyOscar tables (the deb installation is so configured automatically) then load them (replace ***** with the MySQL root password and oscar_mcmaster with the name of the 12_1 database)

$ mysql -uroot -p********* oscar_mcmaster < $HOME/src/oscar_source/oscar/database/mysql/updates/update-phr-docs.sql 

Restart tomcat 6

sudo /etc/init.d/tomcat6 restart

When you login as oscardoc, go to the top menu "pref", near the bottom of the screen will be "set myoscar login id".

Enter the provider username you created above and save it.

Go to the patients master file record and hit "edit". On the right hand column between "country of origin" and "sin" should by " Register for MyOSCAR" option link. 

The subsequent screen should prompt you for your myoscar password. Once you fill that in, it should pre-populate most of the patients information. A username and initial password is supplied for the patient which you may edit, check off the provider(s) who should be allowed to access that chart, and if the patient should be allowed to contact them, then submit.  You will be given the option of printing the username and password for the patient to take home.

A warning "The user and corresponding permissions have been added. All checked providers must authorize this demographic as "patient" from the OSCAR Personal Health Record message screen before the patient can communicate with them. " .

If you now go back to the patient ui, you should be able to login with that username/password.
On the left menu of the patient ui, there should be "messages", click on that. Click on "send new message". The "to" list should have your provider as an option, put in a test subject and a test message and send it. On the patient ui, on the left menu should be a "sent" option, you should now notice the message you just sent is in that list.

If you now go back to the oscar ui as the provider, click on the "myoscar" option on the top menu of the appointment/schedule screen. It should default to the inbox and you should see your test message. You should be able to reply etc to the message as well and verify that in the patient ui the patient sees the response etc.

Security Considerations

Securing your MyOscar box is beyond the scope of this paper.  However as MyOscar is designed to be accessible over the internet, we should be conscious of the issues.

The MyOscar client / patient ui by the nature of it's purpose, is meant to have an open port on the internet for patients to use.

The MyOscar server by virtue of it's design purpose is also meant to have an open port on the internet as other "Oscars" are suppose to be able to communicate with it. If you are not giving anyone else access to your MyOscar server then there's no need to forward or open *that* port.  So in most cases, keep that one closed.

Oscar itself is an in between case.  You mostly will access it on your LAN and only certain parties at certain locations will need to access it remotely. As described in security hardening, if you want to access it outside the LAN (and that is convenient), then for the few machines that need to do so you can can build an SSH tunnel with key authentication.

As for whether all 3 of these services are on the same machine or not, it should not really matter, however we have run into intermittent ssl_error_internal_error_alert with Firefox (only) on servers running both Tomcat 6 and Tomcat 7 on the same JVM.

You should not be opening any machine to the internet in any case. In theory you should only be opening the ports you need, i.e. the Myoscar client's http port. This makes it no less secure than any other http port on the planet like ebay's or your banks, or anything else.

To be nit picky about internal security, you could put all 3 applications on 3 different physical servers, heck why not put the database on a 4th server too, and have different passwords on all 4 servers and put firewalls up between all of them. You need to decide your effort vs returns. There would have to be a serious error/flaw in one of the applications web pages before anything else is compromised let alone significantly compromised.