OSCAR Setup Guide
This setup guide creates an Ubuntu 10.04.4 LTS Virtual Machine with the latest development snapshot of OSCAR. Although this installation procedure uses the Eclipse IDE, it may also be done in an alternative IDE 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.
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.
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. However, in order to avoid dependency issues, we will first install Java OpenJDK, and then later transfer over to the Java Oracle JDK.
sudo apt-get install openjdk-6-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 maven2
sudo apt-get install git-core git-gui
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:
JAVA_HOME="/usr/lib/jvm/java-6-openjdk"
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
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 to checkout the master branch of OSCAR, do the following commands:
mkdir -p ~/workspace/oscar
cd ~/workspace/oscar
git clone git://oscarmcmaster.git.sourceforge.net/gitroot/oscarmcmaster/oscar
Then 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.
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;
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!
Since there are some incompatibility issues with OSCAR and the OpenJDK, we need to transfer our main Java runtime to the Oracle 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".
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
Tomcat should be stopped temporarily as we change the Jave versions.
sudo /etc/init.d/tomcat6 stop
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.
sudo vi /etc/profile
Edit the following lines to the file to reflect the new Java:
JAVA_HOME="/usr/lib/jvm/jdk1.6.0_33"
Then we need to make sure the console knows of the changes.
source /etc/profile
Lastly, we need to uninstall the old OpenJDK from the system.
sudo apt-get purge openjdk*
Before accepting, make sure it specifies that it will only remove anything openjdk related. If it says it will also install other packages such as tomcat and mysql, do not proceed with it. You may need to update the dependencies and/or restart the Virtual Machine. If it says it will only remove the openjdk packages, go ahead and proceed.
Afterwards, we need to restart the Tomcat server. With any luck, Tomcat will start up using the new JDK.
sudo /etc/init.d/tomcat6 restart
Note: This procedure is relatively finicky and is not guaranteed to work.
Should you wish to secure the OSCAR installation, refer to: http://www.oscarmanual.org/oscar_emr_12/developers/installation/security-hardening
SCOOP is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
