Oscar 15 Setup Guide [Under Review]
Contributed by the LEAD Lab
This setup guide will create a new development environment of OSCAR 15 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 Ctrl+Shift+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.
These are the software versions we are currently using.
- Ubuntu 14.04.4 LTS x64
- VirtualBox 5.0.20
- Sun/Oracle Java 7
- Tomcat 6
- MySQL 5.5.49
- Maven 3.0.5
- Git 1.9.1
- 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.
-
Download and install VirtualBox from virtualbox.org
-
Download Ubuntu 14.04.4 LTS x64 Desktop Operating System. You can get the ISO from here.
-
Create a new Virtual Machine and set Virtual Machine to 4GB RAM, 200GB HD. (Can assign more or less depending on hardware, 4 GB is ideal).
-
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. This step is specifically important since otherwise the machine resolution will be very small.
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-java7-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. It is completely upto you to use vi/gedit for the same. Make sure to use gksu for running gedit. 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
To contribute to the development of Oscar, a Github account is necessary. After creation of a Github account, you can sign in on the UViC Gerrit server hosting the local instance of Oscar.
Since you can only clone the repository through the SSH protocol, we need to have our public key added to the server. To create a public/private key pair you can run the following command:
ssh-keygen -t rsa -C "<[email protected]>"
Choose the default location(/home/<username>/.ssh/id_rsa) for saving the file. You can choose to add a password for additional security but it is optional. After completion of this command, the public key will be stored at ~/.ssh/id_rsa.pub. You can then cat ~/.ssh/id_rsa.pub and copy the contents.
On the Gerrit web interface(after logging in through Github) go to Settings -> SSH Public Keys and select Add Key. In the text area, paste the key and add it. You can then clone the repository on your local machine.
We will now create a new work folder in such a way that it will be compatible with Eclipse
mkdir ~/workspace
cd ~/workspace
You can go to the Gerrit interface for the project where you can see a clone command. For example:
git clone ssh://<username>@gerrit.seng.uvic.ca:29418/seng371/oscar
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/oscar15.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/oscar15.properties
sudo nano $CATALINA_HOME/oscar15.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"
It is important to provide complete access to the 'root' user on localhost for modification of the oscar_master database.
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/<username>/workspace/oscar/local_repo/mysql/mysql-connector-java/3.0.11/mysql-connector-java-3.0.11.jar importCasemgmt $CATALINA_HOME/oscar15.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 should be ready for use. Go to http://localhost:8080/oscar15 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.
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/oscar15
sudo rm $CATALINA_BASE/webapps/oscar15.war
sudo cp ./target/*.war $CATALINA_BASE/webapps/oscar15.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/oscar15 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>/oscar15</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.
Manual Install
Citing this SO answer.
Download the 64-bit Linux from here "compressed binary file" - it has a ".tar.gz" file extension.
Uncompress it
tar -xvf jdk-7u75-linux-x64.tar.gz (64-bit)
The JDK 7 package is extracted into ./jdk1.7.0_75 directory.
Now move the JDK 7 directory to /usr/lib
sudo mkdir -p /usr/lib/jvm
sudo mv ./jdk1.7.0_75 /usr/lib/jvm/
Now run
sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/jdk1.7.0_75/bin/java" 1
sudo update-alternatives --install "/usr/bin/javac" "javac" "/usr/lib/jvm/jdk1.7.0_75/bin/javac" 1
sudo update-alternatives --install "/usr/bin/javaws" "javaws" "/usr/lib/jvm/jdk1.7.0_75/bin/javaws" 1
This will assign Oracle JDK a priority of 1, which means that installing other JDKs will replace it as the default. Be sure to use a higher priority if you want Oracle JDK to remain the default.
Correct the file ownership and the permissions of the executables:
sudo chmod a+x /usr/bin/java
sudo chmod a+x /usr/bin/javac
sudo chmod a+x /usr/bin/javaws
sudo chown -R root:root /usr/lib/jvm/jdk1.7.0_75
Run
sudo update-alternatives --config java
You will see output similar to the one below - choose the number of jdk1.7.0_75 - for example 3 in this list (unless you have have never installed Java installed in your computer in which case a sentence saying "There is nothing to configure" will appear):
$ 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-oracle1/bin/java 1047 auto mode
1 /usr/bin/gij-4.6 1046 manual mode
2 /usr/lib/jvm/java-6-oracle1/bin/java 1047 manual mode
3 /usr/lib/jvm/jdk1.7.0_75/bin/java 1 manual mode
Press enter to keep the current choice[*], or type selection number: 3
update-alternatives: using /usr/lib/jvm/jdk1.7.0_75/bin/java to provide /usr/bin/java (java) in manual mode
Repeat the above for:
sudo update-alternatives --config javac
sudo update-alternatives --config javaws
SCOOP is licensed under a Creative Commons Attribution-ShareAlike 3.0 Unported License.
