OSCAR Setup Guide
Written by Jeremy Ho. Last edited: 3/14/2013
This setup guide creates an Ubuntu 12.04.1 LTS Virtual Machine with the RELEASE 12.1 version 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.
Also note that at the time of writing, the 4.2.7 guide no longer exists, but most of the relevant installation material exists on this page already.
At the time of writing, these are the software versions we are currently using and know should work.
- Ubuntu 12.04.1 LTS x64
- VirtualBox 4.2.6 r82870
- OSCAR EMR Release 12.1
- Sun/Oracle Java 6 r38 (Java 7 is not fully supported yet)
- Tomcat 6
- MySQL 5.5.29
- Maven 3.0.4 (Maven 2.x may encounter bugs)
- Git 1.7.9.5
- Eclipse Juno
Download and install VirtualBox 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 12.04.1 LTS x64 Desktop Operating System.
- You can get the iso from releases.ubuntu.com/12.04.1/. Select the ubuntu-12.04.1-desktop-amd64.iso image from their site.
Note: The 4.2.7 page no longer exists at time of writing.
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
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.
_Note 2: If this section's installation procedure does not work, refer to the Alternative Oracle JDK Installation Notes.
cd ~
wget https://github.com/flexiondotorg/oab-java6/raw/master/oab-java.sh -O oab-java6.sh
chmod +x oab-java6.sh
sudo ./oab-java6.sh
sudo apt-get update && sudo apt-get install sun-java6-jdk
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 maven
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
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/environment
Append the following lines to the file:
JAVA_HOME="/usr/lib/jvm/java-6-sun"
CATALINA_HOME="/usr/share/tomcat6"
CATALINA_BASE="/var/lib/tomcat6"
ANT_HOME="/usr/share/ant"
Because of the order in which we installed the packages, it is likely that Ubuntu has changed the default Java from our manually installed Oracle version back to the OpenJDK version. To correct that, we do the following:
sudo update-alternatives --config java
sudo update-alternatives --config javac
sudo update-alternatives --config javaws
In all 3 of the above, select the "java-6-sun" option if applicable.
Afterwards, restart your Virtual Machine
sudo shutdown -r now
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 ~/workspace
cd ~/workspace
Depending on where you want to get the OSCAR source from, you have a few options. Sourceforge is static and easy to access, but is only recommended if you are deploying.
git clone -b RELEASE_12_1 git://oscarmcmaster.git.sourceforge.net/gitroot/oscarmcmaster/oscar
An alternative is to clone OSCAR from the SCOOP github repository which is closely synced with the gerrit repository and has some features SCOOP is working on. Be sure to have set up an ssh_id key before proceeding for this option.
git clone -b e2e-exporter [email protected]:scoophealth/oscar.git
If you just want read-only access to the SCOOP github repository version, use the following.
git clone -b e2e-exporter git://github.com/scoophealth/oscar.git
Or you may refer to the Development Environment Setup towards the end of this page on how to create your own gerrit account and access the official source code directly. Be sure to have set up an ssh_id key before proceeding for this option.
git clone -b RELEASE_12_1 ssh://[email protected]:29418/oscar
where xxxx is your Gerrit username.
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 cleanto clear the Maven repository before trying to recompile again.
After a successful compilation, we deploy OSCAR by copying the generated war file into Tomcat's directory.
sudo cp ~/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 ~/workspace/
git clone git://oscarmcmaster.git.sourceforge.net/gitroot/oscarmcmaster/oscar_documents
cd ~/workspace/oscar_douments
mvn -Dmaven.test.skip=true clean package
sudo cp ~/workspace/oscar_documents/target/*.war $CATALINA_BASE/webapps/OscarDocument.war
Afterwards, we will set up the database that OSCAR will use.
cd ~/workspace/oscar/database/mysql
Replace "xxxx" with the password you set up originally in MySQL.
./createdatabase_bc.sh root xxxx oscar_12_1
Then the OSCAR environment needs to be set up in Tomcat
sudo cp ~/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
TMP_DIR: /var/lib/tomcat6/webapps/OscarDocument/oscar_mcmaster/export/
For BC users edit the following. Once again, replace xxxx with your own defined password:
db_name = oscar_12_1
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 ~/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_1
mysql> insert into issue (code,description,role,update_date,sortOrderId) select icd9.icd9, icd9.description, "doctor", now(), '0' from icd9;
mysql> quit;
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!
Note 2: At this point, you are done installing and setting up OSCAR. The following sections are supplemental addendum that may be helpful.
In order to have a reliable development environment for working on OSCAR, we need to make sure we have the following:
- Personal SSH Key
- Gerrit Account
- Eclipse Juno
- Maven Integration Setup
- Remote Tomcat Debugging
- Remote Tomcat Deployment
Please note that before you read and perform this section, we assume that you know what you are getting yourself into for development and that you have already compiled and deployed OSCAR at least once on your development platform via command line.
If you do not have your own ssh key yet, you can generate a new key-pair. This can be done in command line. Make sure to insert your own email in the [email protected] part.
ssh-keygen -t rsa -C "[email protected]"
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.
If you already do have an ssh key-pair, you can place your id_rsa and id_rsa.pub files in your local .ssh folder.
Note: Current OSCAR development goes through Gerrit, a tracking system for Git. Should you wish to participate in the development, it is strongly recommended that you set yourself up to use Gerrit.
At this point, we swap over to 4.2.5 IDE Install of OSCAR.
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.
Use the existing SSH key that you just set up. If you have an SSH key already, just copy and paste the contents of your id_rsa.pub into their field and click add. You can do this multiple ways, one of which could be
cat ~/.ssh/id_rsa.pub
which will print out that file. Select and copy that to Gerrit.
At the time of writing, we are currently using Eclipse IDE for Java Developers, Version Juno Service Release 1. This build now contains Git and Maven integration by default, so we no longer have to set up those plugins manually.
We will not be using the version of Eclipse that comes with Ubuntu 12.04. Instead, we will use the version of Eclipse found on their website.
Direct Link: http://eclipse.org/downloads/packages/eclipse-ide-java-developers/junosr1
Once you download the appropriate version of the IDE, unpack the zip to wherever you want to deploy it at, and start the program.
By default, Eclipse will create and look for your "workspace" at ~/workspace, which is why we downloaded the OSCAR git repo into that directory.
To import that project into Eclipse, select File > Import.. and then select Existing Projects into Workspace under the General folder.
Select the ~/workspace/oscar directory, and you should be able to finish. Eclipse will then import the project, and then Eclipse should be set up.
Basic Maven Integration
In order to have Eclipse be able to compile with Maven, the m2e plugin needs to know where to find the external Maven tool. If you were following the installation guide from earlier, you should have Maven 3.0.4 installed at /usr/share/maven.
With Eclipse open, select Window > Preferences. Then go to Maven > Installations. You should see an embedded Maven version which is ultimately not what we want.
Click the Add button, and navigate through to /usr/share/maven and click OK. Eclipse should now autopopulate the settings.xml field and you should be able to have Maven build directly within Eclipse.
To have our OSCAR project use the external Maven tool, we will want it to know what Maven goal we are targetting. As that we typically compile with mvn -Dmaven.test.skip=true verify, that means our goal is to verify, and to skip any tests.
Click on Run > Run Configurations… . Then right click on the Maven Build entry, and select New. Specify the base directory to be your oscar root folder (i.e. /home/oscar/workspace/oscar), the Goals to be verify and check in Skip Tests. Make sure you have the Maven Runtime pointed to your external one, save, and run. If everything works, you should see the familiar Maven output in Eclipse console and it should compile OSCAR as expected.
Full Maven to Tomcat Integration
Should you wish to compile and deploy directly to your Tomcat server, you can change the Maven goal to tomcat:deploy or tomcat:redeploy from verify if you add the following section to the pom.xml file in the OSCAR root directory:
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>tomcat-maven-plugin</artifactId>
<version>1.1</version>
<configuration>
<server>myserver</server>
<url>http://localhost:8080/manager</url>
<path>/oscar12</path>
</configuration>
</plugin>
You will want to add this section inside the element.
As well, you need to configure Maven to have knowledge of a server. To do that, create a new settings.xml file in the .m2 folder:
sudo vi ~/.m2/settings.xml
In that file, copy the following into it and save it.
<settings>
<servers>
<server>
<id>myserver</id>
<username>USER</username>
<password>PASS</password>
</server>
</servers>
</settings>
Where USER and PASS are the fields you specified when you set up Tomcat Manager for remote management. You can find instructions to install Tomcat Manager in the Remote Tomcat Deployment section below.
With those files set up, you should be able to do a mvn -Dmaven.test.skip=true tomcat:deploy or tomcat:redeploy and it will compile and automatically place it onto the running server.
Tomcat can support remote debugging if the server starts with the proper settings.
To enable this feature, do the following:
sudo vi /etc/default/tomcat6
Look for the following line and uncomment it:
JAVA_OPTS="${JAVA_OPTS} -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"
So for example, the section could look something like this:
JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m -Xms1024m -XX:MaxPermSize=512m -server -XX:+UseConcMarkSweepGC"
…
JAVA_OPTS="${JAVA_OPTS} -Xdebug -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n"
Save the file, and perform a sudo /etc/init.d/tomcat6 restart to reboot the Tomcat server.
In order to take advantage of this in Eclipse, we need to let Eclipse know where to connect.
Go to Run > Debug Configurations… and then right click Remote Java Application and create a new entry. By default, it should set the project as oscar, the host as localhost, and port as 8000. If they aren't set like that, make sure you change them appropriately. Save this configuration, and you should be able to debug a running Tomcat instance of OSCAR and add breakpoints and trace as you see fit.
Tomcat's Manager feature allows remote access to the Tomcat server for deployment and management of server packages. Please bear in mind that you will need to harden the security of Tomcat should you wish to do this on a production server.
You will need Tomcat6-admin and curl for this section to work.
sudo apt-get install tomcat6-admin curl
After they are installed, go to your tomcat-users.xml file in your Tomcat installation to enable a user to access the manager.
sudo vi $CATALINA_BASE/conf/tomcat-users.xml
Add the following lines inside the tag:
<role rolename="manager"/>
<user username="USER" password="PASS" roles="manager"/>
Where USER is your new username and PASS is your new password. Afterwards, restart your tomcat to have the changes come into effect.
sudo /etc/init.d/tomcat6 restart
After the restart, visit http://localhost:8080/manager/html and login with the credentials you made earlier. What you should expect to see is a page giving you the overall status of the Tomcat server. You should see our drugref2 and oscar12 applications installed and running. Here you can manage them, undeploy, and/or redeploy oscar12 with a newer .war file.
Should you wish to do this in command line, you may also do so with curl.
This command undeploys (uninstalls) oscar12 from the Tomcat server. This is required in order to install a newer version of OSCAR onto the server.
curl http://USER:PASS@localhost:8080/manager/undeploy?path=/oscar12
This command deploys the new OSCAR onto the server based on the oscar-1.0-SNAPSHOT.war file. Make sure your terminal is in the same directory as your war file for this to work. Our instructions will typically have you find the war file at ~/workspace/oscar/target.
curl --upload-file oscar-1.0-SNAPSHOT.war http://USER:PASS@localhost:8080/manager/deploy?path=/oscar12
Performing these two commands will hot swap your OSCAR installation to the new version without having to restart the tomcat server.
_Note: Doing this hot swapping many times however will appear to cause memory leaks and strange CPU usage spikes. It is advised to restart your tomcat server periodically if you intend to hot swap very often.
This section contains extra procedures and notes that you may be useful. However, they may not be up to date and are kept here for archival reasons.
Should you wish to secure the OSCAR installation, refer to: http://www.oscarmanual.org/oscar_emr_12/developers/installation/security-hardening
Manual Install
Go to http://www.oracle.com/technetwork/java/javase/downloads/index.html and select Java SE 6 Update 38 JDK. Click its download button. Accept the license, and download the "jdk-6u38-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-6u38-linux-x64.bin
sudo mkdir /usr/lib/jvm
sudo mv jdk-6u38-linux-x64.bin /usr/lib/jvm/jdk-6u38-linux-x64.bin
cd /usr/lib/jvm
sudo ./jdk-6u38-linux-x64.bin
After it installs, remove the installer package.
sudo rm jdk-6u38-linux-x64.bin
Afterwards, we need to let Ubuntu know that we are using this version of Java.
The following lets Ubuntu know of the existence of this Java installation.
cd ~
sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk1.6.0_38/bin/java" 1
sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk1.6.0_38/bin/javac" 1
sudo update-alternatives --install "/usr/bin/javaws" "javaws" "/usr/lib/jvm/jdk1.6.0_38/bin/javaws" 1
After that is done, make sure Ubuntu knows which Java installation you want to use as default. Select the "jdk1.6.0_38" version that you installed in the menu that appears.
sudo update-alternatives --config java
sudo update-alternatives --config javac
sudo update-alternatives --config javaws
Java 7
Note: Should OSCAR move over to Java 7, these instructions will become relevant. At the time of writing, Java 7 is still somewhat incompatible with OSCAR.
Add an external repository to Ubuntu
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
Install Oracle Java 7
sudo apt-get install oracle-jdk7-installer
Verify that Java is installed correctly
update-alternatives -display java
java -version
javac -version
Add JAVA_HOME to your environment
sudo vi /etc/environment
Append this line to the end of the file and save:
JAVA_HOME=/usr/lib/jvm/java-7-oracle
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
SCOOP is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
