OSCAR Setup Guide
Written by Jeremy Ho. Last edited: 1/22/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.
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.
Add an external repository to Ubuntu
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
Install Oracle Java 7 (or 6 - just change the number)
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
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
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:
CATALINA_HOME="/usr/share/tomcat6"
CATALINA_BASE="/var/lib/tomcat6"
ANT_HOME="/usr/share/ant"
export 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
Note: If you only require a deployment of OSCAR and have no intentions of developing OSCAR code, skip to the "Command Line Setup" section.
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.
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
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
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.
git clone -b e2e-exporter [email protected]:scoophealth/oscar.git
Or you may refer to the Eclipse instructions on how to create your own gerrit account and access the official source code directly.
git clone -b RELEASE_12_1 ssh://[email protected]:29418/oscar
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.
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 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
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;
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 addenums that may be helpful.
Should you wish to remotely redeploy oscar12 in the future to the Tomcat server, you can do so with Tomcat's Manager feature. 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.
Should you wish to secure the OSCAR installation, refer to: http://www.oscarmanual.org/oscar_emr_12/developers/installation/security-hardening
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-6u35-linux-x64.bin
sudo mkdir /usr/lib/jvm
sudo mv jdk-6u35-linux-x64.bin /usr/lib/jvm/jdk-6u35-linux-x64.bin
cd /usr/lib/jvm
sudo ./jdk-6u35-linux-x64.bin
After it installs, remove the installer package.
sudo rm jdk-6u35-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_35/bin/java" 1
sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk1.6.0_35/bin/javac" 1
sudo update-alternatives --install "/usr/bin/javaws" "javaws" "/usr/lib/jvm/jdk1.6.0_35/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_33" version that you installed in the menu that appears.
sudo update-alternatives --config java
sudo update-alternatives --config javac
sudo update-alternatives --config javaws
SCOOP is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
