OSCAR Setup Guide
Written by Jeremy Ho. Edited by Ryan Habibi. Last edited: 11/5/2014
This setup guide will create a new development environment of OSCAR on Ubuntu within a virtual environment. Although this guide is focused primarily on creating a development environment for OSCAR, this guide can also give instructions for just OSCAR deployment. Eclipse is the main IDE used by the OSCAR developer community, but other alternative IDEs may also be used.
In order to be successful with this guide, you should be comfortable working with Linux, the command line, and a 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.
This guide was derived from the 4.2.5 and 4.2.7 pages of the oscarmanual. Unfortunately at the time of writing, the 4.2.7 oscarmanual guide no longer exists.
These are the software versions we are currently using.
- Ubuntu 12.04.4 LTS x64
- VirtualBox 4.3.12
- Sun/Oracle Java 6 r45
- Tomcat 6
- MySQL 5.5.37
- Maven 3.0.4
- Git 1.7.9.5
- Eclipse Luna
Following steps A1 to A15 will set up a virtual machine with a running OSCAR instance.
Following steps B1 to B3 will add add an Eclipse development environment to the virtual machine.
Use the Virtual Machine Usage Notes section to model your development cycle with OSCAR.
Additional appendices are included for more specialized deployment usages of supporting technologies.
Download and install VirtualBox from virtualbox.org
Download Ubuntu 12.04.4 LTS x64 Desktop Operating System.
- You can get the ISO from releases.ubuntu.com/12.04.4/. Select the
ubuntu-12.04.4-desktop-amd64.isoimage from their site.
Create a new Virtual Machine and set Virtual Machine to 2GB RAM, 200GB HD. (Can assign more or less depending on hardware)
- Select the VDI format when creating the hard drive file type
Select the Ubuntu ISO when prompted for disk image
When installation is finished, select Insert Guest Additions from the Devices drop down in VirtualBox.
Since OSCAR and Tomcat are built on Java, we require the Java JDK.
Note: OSCAR needs the Java JDK released by Oracle, not the OpenJDK version.
Run the following in order
sudo add-apt-repository ppa:webupd8team/java
sudo apt-get update
sudo apt-get install oracle-java6-installer
_Note: If the add-apt-repository command cannot be found or does not work, run the following and then try the above again
sudo apt-get install python-software-properties
Note 2: If Step A2 doesn't work, refer to Appendix E: Alternative Oracle JDK Installation Notes.
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 (by putting a backslash before each special character) when reentering the password (p&ss).
Run the following command and create a password when prompted
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 maven git-core
For OSCAR to work correctly, Ubuntu requires a few environment variables.
We will use nano as a text editor. Run the following command
sudo nano /etc/environment
Append the following lines to the file (DO NOT COPY AND PASTE)
JAVA_HOME="/usr/lib/jvm/java-6-oracle"
CATALINA_HOME="/usr/share/tomcat6"
CATALINA_BASE="/var/lib/tomcat6"
ANT_HOME="/usr/share/ant"
Recommended: Upon completion, restart Ubuntu (this can be done by shutting the virtual machine down or standard power cycle) with sudo shutdown -r now
If you do not have your own ssh key, 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. External guide
Run the following command with your email
ssh-keygen -t rsa -C "[email protected]"
When prompted press enter to save to default location: /home/yourusername/.ssh/id_rsa , press enter to accept the default location.
This creates an SSH keypair with the name id_rsa and id_rsa.pub. If you change this, then you must continue to change it throughout the remaining steps.
Optionally: add a password to the SSH for increased security
This generates a public key (id_rsa.pub) and private key (id_rsa).
Go to github.com and create an account if you don't already have one.
Once logged into the account you plan to develop with, go to settings and locate the SSH keys section.
Select add SSH key, choose a name and run the following command in Ubuntu command line to retrieve your SSH key
cat ~/.ssh/id_rsa.pub
Copy and paste the key into github and click add key.
We will now create a new work folder in such a way that it will be compatible with Eclipse
mkdir ~/workspace
cd ~/workspace
Clone OSCAR from the SCOOP github repository which is closely synced with the official gerrit repository.
Run the following command to set up an editable OSCAR master copy
git clone [email protected]:scoophealth/oscar.git
If the above does not work, try the following instead for a read-only OSCAR master copy
git clone git://github.com/scoophealth/oscar.git
If you require a different branch like RELEASE_12_1, add a -b argument and the desired branch after it. For example
git clone -b RELEASE_12_1 [email protected]:scoophealth/oscar.git
Change to the base directory of OSCAR's source code
cd ~/workspace/oscar
Next we'll clean maven to ensure it's ready to work with
mvn clean
Now compile OSCAR with Maven
mvn -Dmaven.test.skip=true package
Note: If this step fails it may be due to dependency errors. You will know if it succeeded as upon completion there will be a final output of "BUILD SUCCESSFUL". If any other message is shown run the following command and repeat the clean and compile commands in order as well.
rsync -av ~/workspace/oscar/local_repo/ ~/.m2/repository/
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. OSCAR Documents is a second .WAR file which is required for OSCAR to run.
cd ~/workspace/
git clone git://oscarmcmaster.git.sourceforge.net/gitroot/oscarmcmaster/oscar_documents
cd ~/workspace/oscar_documents
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_master
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 nano $CATALINA_HOME/oscar12.properties
In Nano, press ctrl+w to search. The following lines should be in the document but commented out with a '#'. For ease of use, copy and paste (right click paste works in nano) the following lines near the existing ones
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 as required (values may need to be modified or whole lines may need to be uncommented). Once again, replace xxxx with your own MySQL password:
db_name = oscar_master?zeroDateTimeBehavior=round&useOldAliasMetadataBehavior=true&jdbcCompliantTruncation=false
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-
HL7TEXT_LABS=yes
Under the caisi plugins section set: program=off
If you require a scheduled E2E patient export service, uncomment and edit the values below. As this service outputs RESTFul multi-part POST requests, make sure you direct E2E_URL to somewhere that can handle those requests.
ModuleNames=E2E
E2E_URL = http://localhost:3001/records/create
E2E_DIFF = on
E2E_DIFF_DAYS = 14
If you need to work with OSCAR 14's new UI, the REST module needs to be enabled:
ModuleNames=REST
Exit nano with ctrl+x, input 'y' to save and press enter.
Then we need to edit Tomcat's environment to have more memory to work with.
sudo nano /etc/default/tomcat6
Find the following line, be aware that there are multiple lines which start with JAVA_OPTS, and uncomment if needed by removing the '#' at the beginning. Ensure that the parameters match what is below:
JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m -Xms1024m -XX:MaxPermSize=512m -server -XX:+UseConcMarkSweepGC"
Explicitly define the connector for MySQL. Replace yourusername with your actual user name.
Note: If you are unable to get this command to work, it should be safe to skip over this step.
java -cp .:/home/yourusername/workspace/oscar/local_repo/mysql/mysql-connector-java/3.0.11/mysql-connector-java-3.0.11.jar importCasemgmt $CATALINA_HOME/oscar12.properties
Insert a base value into the issue table (to prevent problems later), replace xxxx with your MySQL password
mysql -uroot -pxxxx -e 'insert into issue (code,description,role,update_date,sortOrderId) select icd9.icd9, icd9.description, "doctor", now(), '0' from icd9;' oscar_master
OSCAR needs a drug database loaded. To do that we will download the latest version of the Drugref database, set it up, and have it write into the database.
sudo mkdir /usr/local/temp
sudo chmod 666 /usr/local/temp
wget https://demo.oscarmcmaster.org:11042/job/drugref2Master/lastSuccessfulBuild/artifact/target/drugref2.war
sudo mv drugref2.war $CATALINA_BASE/webapps/drugref2.war
We then need to create a new drugref2.properties file.
sudo nano $CATALINA_HOME/drugref2.properties
Add the following into the file and remember to replace xxxx with your MySQL password:
db_user=root
db_password=xxxx
db_url=jdbc:mysql://127.0.0.1:3306/drugref
db_driver=com.mysql.jdbc.Driver
Exit nano with ctrl+x, input 'y' to save and press enter.
Then we need to create a new database to hold the drugref. Remember to replace xxxx with your MySQL password.
mysql -uroot -pxxxx -e "CREATE DATABASE drugref;"
Next we inform OSCAR where DrugRef is located
sudo nano $CATALINA_HOME/oscar12.properties
Add/edit the following into the file:
drugref_url=http://localhost:8080/drugref2/DrugrefService
Exit nano with ctrl+x, input 'y' to save and press enter.
To apply all the changes to the Tomcat server, we need to restart it
sudo /etc/init.d/tomcat6 restart
We'll need to install lynx for the next step
sudo apt-get install lynx
Now we load the complete data into our drugref database. This will take a considerable amount of time (30 minutes to an hour). Do not close or use terminal while working (will hang "waiting for response").
lynx http://localhost:8080/drugref2/Update.jsp
When completed you will be prompted to allow a cookie, allow this always by selecting yes.
Note: While waiting for this to complete, you may start another terminal window and start working on Step A15.
Oscar should be ready for use. Go to http://localhost:8080/oscar12 and login with the following credentials.
User Name: oscardoc
Password: mac2002
2nd Level Passcode: 1117
Note: OSCAR will likely prompt you for a new password after the first login. Go ahead and change the password and make sure to remember what it is.
When logged in, click on Administration on menu bar. Under user management in the side bar select Search/Edit/Delete Security Records and search a blank string. Oscardoc should be returned, click the user name and un-check expiry date.
Return to the main screen and select preferences on the menu bar. Then scroll down to "Set To Use Rx3" and click it. This will open a new window, check the box and submit.
These instructions will add an Eclipse development environment to the virtual machine built from the previous section.
Run the following commands to return to home and download eclipse:
cd ~
wget http://mirror.csclub.uwaterloo.ca/eclipse/technology/epp/downloads/release/kepler/SR2/eclipse-jee-kepler-SR2-linux-gtk-x86_64.tar.gz
The following command will unpack the .tar into a folder named eclipse
tar -zxf eclipse-jee-kepler-SR2-linux-gtk-x86_64.tar.gz
To run eclipse, use cd to navigate to the eclipse folder and the following command will open eclipse
./eclipse &
To load OSCAR into Eclipse, the maven project must be imported. File -> Import, open the maven folder and select existing maven projects. Browse root directory and select the oscar folder and click finish.
_Note: Eclipse will take a couple minutes to build the project. If you notice _
Tomcat can support remote debugging if the Tomcat server starts with the proper settings.
To enable this feature, do the following:
sudo nano /etc/default/tomcat6
Search for the following line and uncomment it:
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.
In Eclipse go to Run -> Debug Configurations. On the left, locate Remote Java Application, right click on it and select New. Name it and click browse next to project and select the oscar folder. Leave the default host as localhost, and port as 8000. Apply this configuration and you should be able to debug a running Tomcat instance of OSCAR and add breakpoints/trace/debug. If the connection is refused, restart Tomcat as above.
At this point, you should have a working OSCAR development environment. If you require more integration, refer to Appendicies A and B for more comprehensive Maven/Tomcat integration and deployment.
Developing in OSCAR is generally a develop, compile/redeploy, and test cycle. To compile and redeploy a change in Eclipse (or any other editor) on your local Tomcat instance, you must stop Tomcat, replace the existing .war file and restart Tomcat. To do so follow the below commands:
sudo /etc/init.d/tomcat6 stop
mvn clean
mvn -Dmaven.test.skip=true package
sudo rm -rf $CATALINA_BASE/webapps/oscar12
sudo rm $CATALINA_BASE/webapps/oscar12.war
sudo cp ./target/*.war $CATALINA_BASE/webapps/oscar12.war
sudo /etc/init.d/tomcat6 start
You can run this line to view the live console output from Tomcat
tail -f $CATALINA_BASE/logs/catalina.out
Go to http://localhost:8080/oscar12 and login with the following credentials.
User Name: oscardoc
Password: mac2002 (or whatever you changed this password to)
2nd Level Passcode: 1117
Note: These instructions have not been fully tested and as such are of beta quality
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 auto populate 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 targeting. 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.
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.
Note: These instructions have not been fully tested and as such are of beta quality
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.
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.
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
SCOOP is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
