4.2.7 Building Oscar from Source
This section is a 'how to' for for moderately skilled technical users who want to manually set up their own Oscar system. This allows for newer 'cutting edge' builds than those based on compiled versions available. ***NOTE*** For production work we recommend the latest oscar-mcmaster_XX-YY.deb instructions using compiled binaries available on sourceforge.
This basic install is adequate for a local install of OSCAR that cannot be accessed from outside of the computer that you are installing OSCAR on. Many users prefer to install OSCAR on a server and access it from a browser on another computer; this requires additional security hardening to meet privacy and security requirements.
- v1.0 – initial public release to oscarmanual.org on May 2, 2010
- v1.1 – adjusted date stamp on CVS instructions on May 3, 2010
- v1.2 – removed workarounds after bugfixes committed on May 5th, 2010
- v1.3 – ported to new.oscarmanaual.org on June 26, 2010
- v1.4 – adjusted script for 10_06 release July 1, 2010
- v1.5 – added fix needed for data export July 7, 2010
- v1.6 – typo's fixed July 26, 2010
- v1.7 – screenshots added Aug 23, 2010
- v1.8 – removed some duplicated lines Sept 20, 2010
- v1.9 – adjusted script for 10_12 release on Dec 3, 2010
- v2.0 – adjusted script for Git on March 4, 2011
- v2.1 – added casemanagement setting for new interface – Jun 14, 2011
- v2.2 – added drugref URL settings for properties – Sept 13, 2011
It is assumed that
- You have installed a version of Ubuntu 10.4 LTS "Lucid" (32/64 bit desktop or server with full disc encryption)
- You have a basic level of Linux knowledge
- You can open a Linux terminal
- You can use a Linux text editor
- You can cut and paste EXACTLY the following instructions
OSCAR is predominately written in the Java programming language and thus requires the Java SDK to be built from source. The Java SDK also supports the Tomcat web framework. The following installs Java
First enable the ubuntu lucid partner repository (it's not enabled by default) by editing sources.listA note about the following command – ‘vi’ (for visual editor) is a classic unix editor. First time users usually find other Linux editors easier to use particularly ‘nano’, if you are running in a terminal environment, and ‘gedit’, if you are running with a GUI. If you elect to use an alternative editor, replace ‘vi’ in the commands that follow with your editor of choice
sudo vi /etc/apt/sources.list
Uncomment the following line in /etc/apt/sources.list by removing its preceding #
#deb http://archive.canonical.com/ubuntu lucid partner
This gives you access to certain software from companies (the partners) that have entered into an agreement with Canonical (which develops Ubuntu) such as Oracle (Sun) that provides the type of java that we want.
sudo apt-get update sudo apt-get install sun-java6-jdk
Mouse or [tab] to highlight the <OK> and [enter] to accept it.
Mouse or [tab] to highlight the < yes> acceptance of the license agreement and [enter] to accept it.
Your specific CMS data, profiles, and information will all be stored in the MySQL database.
sudo apt-get install mysql-server libmysql-java
This installation sequence will ask you for a secure password for the database server as below. Enter it, [tab] to the <Ok> and [enter]. You will be prompted to enter the password again to verify.
Remember this password as you will need it again later in the installation whenever ****** is referenced. If you use symbols "#,!, &,*, (, ), / , \ and $" in this password (eg pass&word), be sure to escape them when replacing the ***** (eg pass\&word).
To support OSCAR’s web based user interface, the system leverages the extensive resources of the Apache Tomcat web application framework.
sudo apt-get install tomcat6
sudo apt-get install ant-optional
These are all of the base packages that need to be installed. Now, we will reboot the server.
sudo apt-get install git-core
sudo shutdown -r now
After the server restarts, log in once again, and proceed to the next section.
A few environment variables need to be set to support OSCAR.
sudo vi /etc/profile
If you are configuring OSCAR on a freshly installed Ubuntu server, then you should be safe to add these lines to end of 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" export JAVA_HOME CATALINA_HOME CATALINA_BASE ANT_HOME
To load the new environment variables into your existing terminal, run the following command. Please note that the sudo command is not required in this case.
The infrastructure is now in place and it is time to get the OSCAR source code.
By specifying a particular release, you will get the code from
that branch of the code. For the 10_06 release run the command with -b new_RELEASE_10_06
If the development stream code is what you want (you will if you want to do development work), run the command without -b new_RELEASE_10_12 and you will get "master" (aka trunk).
This tutorial is specific to the commands in the following section.
mkdir -p $HOME/src/oscar_source cd $HOME/src/oscar_source git clone -b new_RELEASE_10_12 git://oscarmcmaster.git.sourceforge.net/gitroot/oscarmcmaster/oscar
It will take a few minutes for the source code to download. Afterward, Compile OSCAR.
cd $HOME/src/oscar_source/oscar/build ant
You may ignore the warnings from the compiler, however you should expect to receive the message: BUILD SUCCESSFUL.
Copy the resulting WAR files to the web server. (There will be disk activity as Tomcat unpacks the wars)
sudo cp $HOME/src/oscar_source/oscar/build/tmp/*.war $CATALINA_BASE/webapps
OSCAR includes scripts to populate the MySQL database. Change to the database script directory.
Only run one of the following two database creation commands (either A or B) !
A.) Users that wish to use Ontario’s billing subsystem should run
the following command (replace ****** with the MySQL password you
B.) Whereas users who wish to use British Columbia’s billing
subsystem should run this command (replace ****** with the MySQL
password you set earlier.):
OSCAR users that are from neither Ontario nor BC can run either of the above commands (you must run one of them, we recommend the Ontario one), then you will need to adjust the billing system according to your own location. Whatever script you run you should get feedback from the script that looks a bit like the following. (note there are no errors reported and the last line reminds about expiring credentials):
If you ever need to reinitialize the database, you can use the same script.
You will need to move the oscar_*.properties files to $CATALINA_HOME as described below.
sudo cp $HOME/src/oscar_source/oscar/web/WEB-INF/classes/oscar_mcmaster.properties $CATALINA_HOME sudo ln -s $CATALINA_HOME/oscar_mcmaster.properties $CATALINA_HOME/oscar.properties
The oscar.properties file needs to be localized for your specific configuration.
Most users will want turn on the new casemanagement interface
sudo vi $CATALINA_HOME/oscar.properties
TIP: The phone prefix prepopulates new demographics and is not limited to the area code (although that may be all that can be predicted in an urban area)
### change to your mysql database password
billcenter=R### change to your local OHIP office code
## Change the password to your mysql database password db_password=*******
## Change the visit location to yours OO|VANCOUVER etc
visitlocation = P1|PEMBERTON ## Change your Id to the one Teleplan supplied you 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 = 604-
sudo vi /etc/default/tomcat6
Find the following sections and configure the variables to match what is below. Use cat /proc/meminfo to determine your system memory. I am assuming below that you have at least 1Gb RAM.
Now we’ll enable access to the new echart interface with a utility that adjusts the database assigning patients and providers to the Oscar program.
# 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"
cd $HOME/src/oscar_source/oscar/database/mysql java -cp .:$CATALINA_BASE/webapps/oscar/WEB-INF/lib/mysql-connector-java-3.0.11-stable-bin.jar importCasemgmt $CATALINA_HOME/oscar.properties
and adjust some tables (replace ****** with the MySQL password you set earlier.
And finally make a directory for Demographic export and allow read and write privileges for anyone.
mysql -uroot -p******
oscar_mcmaster### will bring you to the mysql database prompt
insert into issue (code,description,role,update_date) select icd9.icd9, icd9.description, "doctor", now() from icd9; mysql> quit;### gets you out of mysql
sudo mkdir /usr/local/temp sudo chmod 666 /usr/local/temp
Download the binary and copy the WAR file to $CATALINA_BASE
Either MySQL or Postgres can be used for database. Launch your text editor to form drugref.properties
wget http://drugref2.googlecode.com/files/drugref.war sudo mv drugref.war $CATALINA_BASE/webapps/drugref.war
Enter the following lines into drugref.properties (replace ****** with the MySQL password you set earlier.) and save.
For simplicity MySQL will be used here. Create an empty drugref database with the following (replace ****** with the MySQL password you set earlier.):
mysql -uroot -p*******
mysql> create database drugref; mysql> quit;
sudo vi $CATALINA_HOME/oscar.properties
if you are installing drugref on the same host as Oscar then the url should be as such
sudo /etc/init.d/tomcat6 restart
To populate the database with drug data open your browser and navigate to the server. If you installed on a local desktop version of Ubuntu it is as shown below.
http://localhost:8080/drugref/Update.jsp (If you installed via a SSH tunnel open firewall access for port 8080 on the server and change localhost to its URL)
****NOTHING**** will seem to happen (except for the page loading symbol) for between a quarter and half an hour so get a coffee.
When you get back to the screen you will get a page like.
|Table Name||Number of Rows|
Time spent on importing data: 13 minutes
Time spent on new generic import: 8 minutes
The program will then clean up the Health Canada data and will display something like the following (it may take 4 minutes)Added Descriptor and Strength
Number of drug names being added descriptor: 45
Number of drug names being added strength: 21297
At this point you can test the fairly plain install. To test the connection, open your web browser and go to your the web address of your server. If you installed on a local desktop version of Ubuntu it is as shown below. You should see the OSCAR login page.
The default login parameters for OSCAR is as follows:
User Name: oscardoc
2nd Level Passcode: 1117
Activate Rx3 when logged into Oscar navigate Pref > Set To Use Rx3 and click the check box
If you can login then you have successfully installed a plain OSCAR and you can start playing with it.
This is enough for now, however for production use you will need to secure your installation further and apply basic security hardening