OSCAR Setup Guide

Written by Jeremy Ho. Last edited: 7/16/2012

This setup guide creates an Ubuntu 10.04.4 LTS Virtual Machine with the latest development snapshot of OSCAR. Although its aim is to create a development environment for OSCAR, this guide will also give instructions for just deploying an instance of OSCAR. This guide does outline how to install with the Eclipse IDE, but it may also be done in an alternative IDE of your choice or completely from command line. This guide references the 4.2.5 and 4.2.7 pages of the oscarmanual and follows the installation instructions given on those pages relatively closely. Although you should not need those guides when following this, they do contain screenshots that may be useful to you during the installation process.

In order to be successful with this guide, it is assumed that you are comfortable working with Linux, the command line, and text editor. Any text that appears inside a lightly colored box is a command that needs to be executed in the terminal. Remember that although copy is Ctrl+C, to paste in the terminal (at least for Ubuntu) you need to do Shift+Ctrl+V in order to paste. Anything that is in italics is an installation related note, and anything that is in an indented bullet is a comment.

Environment Setup

Download and install VirtualBox 4.1.18-78361 from virtualbox.org

Create a new Virtual Machine and set Virtual Machine to 2GB RAM, 200GB HD.

• Select the VDMK format if you think you may transfer this VM to VMWare down the road. Otherwise the VDI format works as well.

Download and install the Ubuntu 10.04.4 LTS x64 Desktop Operating System.

• You can get the iso from releases.ubuntu.com/lucid/. Select the ubuntu-10.04.4-desktop-amd64.iso image from their site.

OSCAR Manual

Go to oscarmanual.org and click on "OSCAR EMR version 12". Under "Table of Content", Click on "4.0 Developers Only". Click on "4.2 Installation 11/12". Under "Title", Click on "4.2.7 Building Oscar 12 from Source".

Direct Link: http://www.oscarmanual.org/oscar_emr_12/developers/installation/basic-manual-oscar-install

Infrastructure Installation

Oracle Java 6

Since OSCAR and Tomcat are built on Java, we require the Java JDK.

Note: We want to have the Java JDK released by Oracle, not the OpenJDK version.

Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html and select Java SE 6 Update 33 JDK. Click its download button. Accept the license, and download the "jdk-6u33-linux-x64.bin".

Note: these files will be in the format [java-version]-x64.bin. Select the newer versions should they exist.

We then install the Oracle JDK

cd ~/Downloads

chmod a+x jdk-6u33-linux-x64.bin

mv jdk-6u33-linux-x64.bin /usr/lib/jvm/jdk-6u33-linux-x64.bin

sudo ./jdk-6u33-linux-x64.bin

Afterwards, we need to let Ubuntu know that we are using this version of Java.

sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk1.6.0_33/bin/java" 1

sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk1.6.0_33/bin/javac" 1

sudo update-alternatives --install "/usr/bin/javaws" "javaws" "/usr/lib/jvm/jdk1.6.0_33/bin/javaws" 1

sudo update-alternatives --config java

You will see an output similar to below. Select the /usr/lib/jvm/jdk1.6.0_33/bin/java version from the list.

$sudo update-alternatives --config java

There are 3 choices for the alternative java (providing /usr/bin/java).

Selection Path Priority Status

————————————————————

• 0 /usr/lib/jvm/java-6-openjdk/jre/bin/java 1061 auto mode

1 /usr/lib/jvm/java-6-openjdk/jre/bin/java 1061 manual mode

2 /usr/lib/jvm/java-6-sun/jre/bin/java 63 manual mode

3 /usr/lib/jvm/jdk1.7.0/jre/bin/java 3 manual mode

Press enter to keep the current choice[*], or type selection number: 3

update-alternatives: using /usr/lib/jvm/jdk1.7.0/jre/bin/java to provide /usr/bin/java (java) in manual mode.

Then repeat for both javac and javaws.

sudo update-alternatives --config javac

sudo update-alternatives --config javaws

Supporting Packages

MySQL is used to store OSCAR's specific CMS data, profiles, and other information. You will be asked to create a password for the database. If you use symbols "#,!, &,*, (, ), / , \ and $" in this password (eg p&ss), make sure you escape them later when reentering the password (p&ss).

sudo apt-get install mysql-server libmysql-java

OSCAR's web interface depends on Tomcat, the compilation of OSCAR is managed by Maven, and OSCAR's version control system is done through Git.

sudo apt-get install tomcat6

sudo apt-get install maven2

sudo apt-get install git-core

If you wish to use the Eclipse IDE, do the following optional command.

Optional: sudo apt-get install eclipse

Afterwards, restart your Virtual Machine

sudo shutdown -r now

Configuring Packages

For OSCAR to work correctly, we need to set a few environment variables.

Note: 'vi' is a classic unix editor. If you don't like using that, you may use alternatives such as 'nano' if you are in a terminal environment, or 'gedit' if you are using a GUI. If using an alternative editor, replace 'vi' with your alternate text editor in the commands.

sudo vi /etc/profile

Append the following lines to the file:

JAVA_HOME="/usr/lib/jvm/jdk1.6.0_33"

CATALINA_HOME="/usr/share/tomcat6"

CATALINA_BASE="/var/lib/tomcat6"

ANT_HOME="/usr/share/ant"

export JAVA_HOME CATALINA_HOME CATALINA_BASE ANT_HOME

Afterwards, to update your current terminal session with these new environment variables, have it reread that file with source.

source /etc/profile

Development Environment Setup

Note: If you only require a deployment of OSCAR and have no intentions of developing OSCAR code, skip to the "Command Line Setup" section.

Gerrit Setup

Note: Current OSCAR development goes through Gerrit, a tracking system for Git. Should you wish to participate in the development, it is recommended that you set yourself up to use Gerrit.

At this point, we swap over to 4.2.5 IDE Install of OSCAR. If you are installing by command line, you may skip the Eclipse steps.

Direct Link: http://www.oscarmanual.org/oscar_emr_12/developers/installation/ide-install-of-oscar

Since we want to eventually engage with the development of OSCAR, we need to register on Gerrit. Gerrit is the main web based code review system used by the developers of OSCAR.

Direct Link: https://source.oscartools.org:8080/

Go ahead and make an account on the site. If you encounter an untrusted certificate warning, it is normal because their certificate is self signed.

Create or Use an existing SSH key. If you have an SSH key already, just copy and paste the contents of your id_rsa.pub into their field and click add.

If you do not have an SSH key, you will need to generate a key pair. This can be done in command line.

ssh-keygen -t rsa

Generating public/private rsa key pair.

Enter file in which to save the key (/home/user/.ssh/id_rsa):

Enter passphrase (empty for no passphrase):

Enter same passphrase again:

Your identification has been saved in /home/user/.ssh/id_rsa.

Your public key has been saved in /home/user/.ssh/id_rsa.pub.

Now copy and paste the contents of your id_rsa.pub into their field and click add.

IDE Setup (Eclipse)

Note: Skip this section if you're doing it by command line

Eclipse by default does not have Git support. We need to get a plugin called EGit installed into Eclipse for it to have access to the OSCAR repository.

Open Eclipse and click on Help > Install New Software...

Add in http://download.eclipse.org/egit/updates in the "Work with:" field

Select Eclipse Git Team Provider, hit next twice, then accept the license agreements

Hit finish to install EGit to Eclipse and restart it

Click Window > Preferences > Team > Git > Configuration

Click Add entry… and add in your user.email from your Git settings

Click Add entry… and add in your user.name from your Git settings

Exit out of the settings menu and click File > Import… > Projects from Git, then next

Select URI then next

Use ssh://[email protected]:29418/oscar where xxxx is your Gerrit username. The password is not necessary.

Optional: Uncheck "Store in Secure Store" so you don't need to sign in every time Eclipse opens

Accept the RSA key if it appears and hit next.

Select the "master" branch then hit next. Accept the default settings unless a previous OSCAR directory exists already.

Let Eclipse download from the repository.

Select Import existing projects and click next.

Make sure OSCAR is checked in and Click Finish.

Swap back to the 4.2.7 document

Direct Link: http://www.oscarmanual.org/oscar_emr_12/developers/installation/basic-manual-oscar-install

Command Line Setup

If you did not use Eclipse or an alternative IDE to checkout the master branch of OSCAR, do the following commands to get a copy of OSCAR's source code:

mkdir -p ~/workspace/oscar

cd ~/workspace/oscar

git clone git://oscarmcmaster.git.sourceforge.net/gitroot/oscarmcmaster/oscar

Compile & Deploy OSCAR to Tomcat

Change to the base directory of the source code

cd ~/workspace/oscar

We will compile with Maven

mvn -Dmaven.test.skip=true verify

This will take a while and you can ignore the warnings from the compiler. Expect to get a "BUILD SUCCESSFUL" message when it completes.

• In the event the build fails, make sure you are in the correct directory before Maven compiling. If Maven has attempted to compile already in the wrong directory, do mvn clean to clear the Maven repository before trying to recompile again.

Note: If you are using Eclipse, then click Window > Preferences > Java > Build Path > Classpath Variables > [New...] and add "M2_REPO" and "/home/ubuntu/.m2/repository" to the Classpath

After a successful compilation, we deploy OSCAR by copying the generated war file into Tomcat's directory.

sudo cp $HOME/workspace/oscar/target/*.war $CATALINA_BASE/webapps/oscar12.war

Then we need to get the OSCAR documents checked out, compiled, and deployed to Tomcat.

cd $HOME/workspace/

git clone git://oscarmcmaster.git.sourceforge.net/gitroot/oscarmcmaster/oscar_documents

cd $HOME/workspace/oscar_douments

mvn -Dmaven.test.skip=true clean package

sudo cp $HOME/workspace/oscar_documents/target/*.war $CATALINA_BASE/webapps/OscarDocument.war

Afterwards, we will set up the database that OSCAR will use.

cd $HOME/workspace/oscar/database/mysql

Replace "xxxx" with the password you set up originally in MySQL.

./createdatabase_bc.sh root xxxx oscar_12

Then the OSCAR environment needs to be set up in Tomcat

sudo cp $HOME/workspace/oscar/src/main/resources/oscar_mcmaster.properties $CATALINA_HOME/oscar12.properties

sudo vi $CATALINA_HOME/oscar12.properties

Search for, uncomment and edit the values to the following:

CASEMANAGEMENT=all

DOCUMENT_DIR = /var/lib/tomcat6/webapps/OscarDocument/oscar_mcmaster/document/

eform_image = /var/lib/tomcat6/webapps/OscarDocument/oscar_mcmaster/eform/images

For BC users edit the following. Once again, replace xxxx with your own defined password:

db_name = oscar_12

db_password=xxxx

visitlocation = 00|VANCOUVER

dataCenterId = 00000

billregion=BC

NEW_BC_TELEPLAN=yes

CDM_ALERTS=250,428,4280

COUNSELING_CODES=18220,18120,17220,17120,16220,16120,13220,12220,12120,00120

phoneprefix = 250-

Then we need to edit Tomcat's environment.

sudo vi /etc/default/tomcat6

Find the following section and configure/edit to match what is below:

You may pass JVM startup parameters to Java here. If unset, the default

options (-Djava.awt.headless=true -Xmx128m) will be used.

JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m -Xms1024m -XX:MaxPermSize=512m -server"

We then need to tweak the MySQL server

cd $HOME/workspace/oscar/database/mysql

java -cp .:$CATALINA_BASE/webapps/oscar12/WEB-INF/lib/mysql-connector-java-3.0.11.jar importCasemgmt $CATALINA_HOME/oscar12.properties

Remember to change "xxxx" to your own password.

mysql -uroot -pxxxx oscar_12

mysql> insert into issue (code,description,role,update_date,sortOrderId) select icd9.icd9, icd9.description, "doctor", now(), '0' from icd9;

mysql> quit;

Import & Update Drugref

OSCAR needs a drug database loaded. To do that we will download the latest version of the data, set it up, and have it write into the database.

sudo mkdir /usr/local/temp

sudo chmod 666 /usr/local/temp

wget http://drugref2.googlecode.com/files/drugref.war

sudo mv drugref.war $CATALINA_BASE/webapps/drugref.war

sudo vi $CATALINA_HOME/drugref.properties

Add the following into the file and remember to replace xxxx with your own:

db_user=root

db_password=xxxx

db_url=jdbc:mysql://127.0.0.1:3306/drugref

db_driver=com.mysql.jdbc.Driver

Then we need to create a new database to hold the drugref. Remember to replace xxxx with your own defined password.

mysql -uroot -pxxxx

mysql> create database drugref;

mysql> quit;

sudo vi $CATALINA_HOME/oscar12.properties

Add/edit the following into the file:

drugref_url=http://localhost:8080/drugref/DrugrefService

To apply all the changes to the Tomcat server, we need to restart it

sudo /etc/init.d/tomcat6 restart

Now we load the drugref into the database. Go to http://localhost:8080/drugref/Update.jsp and wait between 15 minutes to 1 hour. It will appear to hang on the browser, but do not stop or close it. It will load in the drugref and upon completion give a table of its operation results.

Oscar should be ready to enter. Go to http://localhost:8080/oscar12 and login with the following credentials.

User Name: oscardoc

Password: mac2002

2nd Level Passcode: 1117

Then click on Pref and then "Set To Use Rx3" and check it in and apply.

Note: Remember to update your login credentials as they will expire in a month!

Security Hardening

Should you wish to secure the OSCAR installation, refer to: http://www.oscarmanual.org/oscar_emr_12/developers/installation/security-hardening

Extra Notes

The following download is a nice script which simplifies changing the default Java runtime environment on the system.

wget http://webupd8.googlecode.com/files/update-java-0.5b

chmod +x update-java-0.5b

sudo ./update-java-0.5b

Select the "/usr/lib/jvm/jdk1.6.0_33" and click OK.