Installation of OSCAR v9.06 + Ubuntu Hardy Heron v8.04 LTS

This tutorial covers the installation of the OSCAR McMaster Clinical Management System (CMS), using the Ubuntu Hardy Heron v8.04 Long Term Support (LTS) operating system.

As this is a mission critical server, we recommend utilizing the latest Ubuntu LTS version as the foundation for your OSCAR installation, as this will deliver the most trouble free and stable platform for your OSCAR.

OSCAR can be installed on two or more servers and deployed in a redundant configuration to provide maximum resiliency in support of your practice. The instructions to install a redundant server configuration is beyond the scope of this tutorial. However, for the adventurous who are interested in this topic, build two identical OSCAR servers, and then search the internet on how to configure MySQL replication for the database, rsync for the filesystem, and cron for the automation. These utilities/tools will allow you to tie your two or more OSCAR servers together.

Preamble

These instructions are written for an audience comfortable with invoking instructions from the command line. If you are capable of installing the user friendly Ubuntu GNU/Linux operating system, then you should be able to follow along with ease.

This installation has been tested with the following standard Ubuntu 8.04 LTS distro packages:

Ubuntu 8.04.1 i386 (32 bit, desktop or server)
tomcat 5.5
mysql 5.0.51a-3Ubuntu5.4
java version 1.5.0_16 (Sun’s java 1.5)
javac version 1.5.0_16
ant version 1.7.0

License

This document, written by David Daley in June 2008, is freely licensed under the Creative Commons Attribution-Share Alike 3.0 Unported License.

Document Version History

v1.0 – initial public release for OSCAR v2.2 – July, 2008
v1.1 – minor modifications, additions, corrections – March, 2009
v1.1a – no content changes (formatted for new webserver) – May, 2009
v1.2 – added specific date stamp to drugref CVS command – May, 2009
v1.3 – fixed formating issue related to quotes – May, 2009
v2.0 – initial public release for OSCAR v9.06 – July, 2009
v2.1 – updated the cvs date to include week view feature – July, 2009
v2.2 – fixed a wayward hyphen – September, 2009

Getting Started

First, you must install Ubuntu 8.04 LTS. The installation of the base operating system is beyond the scope of this document. Ubuntu can be downloaded or ordered in disk format directly over the internet.

Ubuntu runs on inexpensive, commodity hardware. To support a small practice with OSCAR, we recommend a minimum configuration of 200Gb Disk, 2Gb RAM, and a 2GHz Intel Dual Core CPU. For maximum subsystem compatibility, we suggest that you install the 32bit version of Ubuntu. If you are purchasing a computer to run OSCAR, one option is to order the machine with Ubuntu pre-installed.

Please note that OSCAR continues to run very well on hardware that is much less powerful than this practical minumum. For example, OSCAR will run quite reasonably on a machine with a single core CPU with 512Mb RAM and 20Gb disk.

I am assuming that your target computer is connected to the internet. After installing the operating system, log into your machine and open a terminal window.

We are now ready to begin.

Updating The Operating System

It is useful to update your system with the latest components and system patches. The first command below asks Ubuntu to update its database of available packages, and the second command installs the latest packages based on your current configuration. We run the upgrade command twice to ensure that any packages that may have post-upgrade dependancies, also have an opportunity to be upgraded.

From the command line, enter the following commands, one at a time.

sudo apt-get update

sudo apt-get -u upgrade

sudo apt-get -u upgrade

The sudo command is used to run priviledged operations on the Ubuntu platform. The first time you run the command, it will ask for your password. Subsequently, it will not ask for your password again for a short period of time (typically 15 minutes).

apt-get is the program Ubuntu uses for managing the system’s packages. When used to manipulate the core packages of the operating system, it needs to be run in conjunction with the sudo command.

Installing The Infrastructure Packages

In order to support secure remote connections to your server, you will need to install the OpenSSH package. This package will come in handy in the future to support administrative tasks on the system.

sudo apt-get install openssh-server

To log into a remote computer that is running OpenSSH, you use the ssh username@hostname command, replacing username with a valid user name on the computer you are trying to log into, and replacing hostname with either the fully qualified host name (e.g. example.com) of your server, or it’s IP address (e.g. 192.168.0.17).

For example, if your everyday computer is a Mac, and your OSCAR server user account is david, and your OSCAR server IP address is 192.168.2.200, then you can now log into your server from your Mac, by opening a terminal window on your Mac and running the command ssh david@192.168.2.200.

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, plus fixes a bug in its default installation program. The server will need to be rebooted to catch this fix, but we will do this later.

sudo apt-get install sun-java5-jdk

sudo ln -s /usr/lib/jvm/java-1.5.0-sun/jre/lib/i386/libmlib_image.so /usr/lib

sudo ldconfig

The source code compilation process for OSCAR is managed by the Ant package.

sudo apt-get install ant-optional

Your specific CMS data, profiles, and information will all be stored in the MySQL database. This installation sequence will ask you for a secure password for the database server – remember this password as you will need it again later in the installation.

sudo apt-get install mysql-server libmysql-java

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 tomcat5.5 tomcat5.5-admin

sudo ln -s /usr/share/tomcat5.5 /usr/local/tomcat

OSCAR backup can be configured to use the Pretty Good Privacy subsystem.

sudo apt-get install pgpgpg

Concurrent Versions System (CVS) is used for source code control on the OSCAR Project. You will need this package to grab the OSCAR source code.

sudo apt-get install cvs

OSCAR’s prescription drug & allergy database, DrugRef, requires the PostgreSQL database.

Please note that the sudo command is not required for the following export and unset commands.

export LC_ALL=C

sudo apt-get install postgresql-8.3 python-pgsql

unset LC_ALL

If you are installing OSCAR on the Ubuntu 8.04 LTS Server Edition, the default package will not include unzip. We’ll install that now (note: if your Ubuntu is the Desktop Edition, then you can skip this step.

sudo apt-get install unzip

To keep OSCAR’s clock synchronized with the world, we recommend you install the Network Time Protocol (NTP) service. This will require that your OSCAR maintains a link to the Internet to work.

sudo apt-get install ntp

These are all of the base packages that need to be installed. Now, we will reboot the server.

sudo shutdown -r now

After the server restarts, log in once again, and proceed to the next section.

Configuring The Base Packages

A few environment variables need to be set to support OSCAR.

A note about the following command – ‘vi’ (for visual editor) is a classic unix editor (classic, in the sense of, you have to know it to really love it). Alternative editors exist. Examples of other Ubuntu editors include ‘nano’, if you are running in a terminal environment, and ‘gedit’, if you are running with a GUI. ‘emacs’ lovers need to install the emacs package via apt-get before you can use it as it is not part of the base distro. If you elect to use an alternative editor, replace ‘vi’ in the commands that follow with your editor of choice.

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-1.5.0-sun"

CATALINA_HOME="/usr/share/tomcat5.5"

ANT_HOME="/usr/share/ant"

export JAVA_HOME CATALINA_HOME 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.

source /etc/profile

The infrastructure is now in place and it is time to get the OSCAR source code. The first cvs command below will ask you for a password – please respond by hitting the Enter key, without adding a password (ie a null password).

By specifying a specific date/time on the checkout command, you ensure that you get a specific, dated version that you can track from. The command, run without the datestamp verb -D "2009-06-30 23:59:59" will retrieve the most recent version.

By specifying a particular release, you will get the code from that branch of the code. The command, run without the release flags, will get you the code from the development branch. If the development stream code is what you want, run the command without -r and also without -r RELEASE_9_06.

This tutorial is specific to the commands in the following section.

mkdir -p $HOME/src/oscar_source

cd $HOME/src/oscar_source

cvs -d:pserver:anonymous@oscarmcmaster.cvs.sourceforge.net:/cvsroot/oscarmcmaster login

cvs -z3 -r -d:pserver:anonymous@oscarmcmaster.cvs.sourceforge.net:/cvsroot/oscarmcmaster co -r RELEASE_9_06 -D "2009-07-20 23:59:59" oscar_mcmaster

cvs -d:pserver:anonymous@oscarmcmaster.cvs.sourceforge.net:/cvsroot/oscarmcmaster logout

It will take a few minutes for the source code to download. Afterwards, compile OSCAR.

cd $HOME/src/oscar_source/oscar_mcmaster/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.

sudo cp $HOME/src/oscar_source/oscar_mcmaster/build/tmp/*.war $CATALINA_HOME/webapps

OSCAR includes scripts to populate the MySQL database. For the following set of commands, you need to replace ****** with a secure password. Remember this password as it will be required to administer the database.

cd $HOME/src/oscar_source/oscar_mcmaster/database/mysql

Only run one of the following two database creation commands!

Users that wish to use Ontario’s billing subsystem should run the following command:

./createdatabase_on.sh ****** oscar_mcmaster

Whereas users who wish to use British Columbia’s billing subsystem should run this command:

./createdatabase.sh ****** oscar_mcmaster

OSCAR users that are from neither Ontario nor BC can run either of the above commands (you must run one of them), then you will need to adjust the billing system according to your own location.

You will need to move the oscar_*.properties files to $CATALINA_HOME as describe below.

sudo cp $HOME/src/oscar_source/oscar_mcmaster/install/oscar*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.

sudo vi $CATALINA_HOME/oscar.properties

Specific configuration variables to consider for modification may include the following (but please review all properties for your own situtation):

db_password = oscar2003 ### change to your mysql database password

drugref_url = http://localhost:8001 ### points locally

project_home = oscar

backup_path = /usr/local/backups/ ### change to a place for your backup files

SHOW_APPT_REASON=yes ### uncomment by removing the ‘#’

ENABLE_EDIT_APPT_STATUS=yes ### uncomment by removing the ‘#’

#ticklerplus=on ### disable by adding the ‘#’

#clientdropbox=off ### disable by adding the ‘#’

CASEMANAGEMENT=all ### turn on the new echart

CMESort=UP ### make the echart sort nicely

TESTING=yes ### enables the Invoice Report feature

FILTER_ON_FACILITY=false

If you don’t change the default location for the documentation directories in the properties file, you will need to create the appropriate directories.

sudo mkdir -p /usr/local/tomcat/webapps/OscarDocument/oscar_mcmaster/form/record

sudo chown tomcat55:nogroup -R /usr/local/tomcat/webapps/OscarDocument/oscar_mcmaster/form

The defaults for MySQL will work fine when you are starting out, but you can tune the database so that it will run even faster. First, edit it’s configuration file:

sudo vi /etc/mysql/my.cnf

Find the section that looks like this:

#

# * Fine Tuning

#

key_buffer = 16M

max_allowed_packet = 16M

thread_stack = 128K

thread_cache_size = 8

#max_connections = 100

#table_cache = 64

#thread_concurrency = 10

#

# * Query Cache Configuration

#

query_cache_limit = 1M

query_cache_size = 16M

Assuming that your server has 2Gb RAM and a single, dual core CPU, then the following modifications are reasonable to help accelerate your OSCAR solution. For the lines that exist in the above block, you can just adjust their numbers. For the lines that do not exist, add them to your configuration file.

key_buffer = 384M

table_cache = 512

sort_buffer_size = 4M

read_buffer_size = 4M

read_rnd_buffer_size = 16M

myisam_sort_buffer_size = 64M

query_cache_size = 32M

thread_concurrency = 4

After saving the configuration file, you will need to restart MySQL.

sudo /etc/init.d/mysql restart

We will now configure Tomcat. First, adjust the configuration file to allocate more resources to OSCAR.

sudo vi /etc/default/tomcat5.5

Find the following sections and configure the variables to match what is below. Once again, I am assuming that you have at least 2Gb RAM.

# Arguments to pass to the Java virtual machine (JVM).

JAVA_OPTS="-Xmx1024m -Xms1024m -XX:MaxPermSize=512m"

# Use the Java security manager? (yes/no)

TOMCAT5_SECURITY=no

Save the configuration file and when you are back to the shell, create the SSL certificate (localize the specific values noted in this command for your particular situation and change the default password of “changeit” to something specific for your installation).

sudo $JAVA_HOME/bin/keytool -genkey -dname "CN=192.168.2.200, OU=Indivica, O=Indivica, L=Toronto, ST=Ontario, C=CA" -alias tomcat -validity 3650 -keyalg RSA -keystore /root/.keystore -keypass changeit -storepass changeit

Now, modify Tomcat’s server config file to support secure encrypted connections via SSL.

sudo vi $CATALINA_HOME/conf/server.xml

In the server.xml file, look for the SSL HTTP/1.1 Connector entry and enable that block of configuration code by removing the comment tags (<!– and –>).

Then modify the section to look like the following section.

<!– Define a SSL HTTP/1.1 Connector on port 8443 –>

<Connector port="8443" maxHttpHeaderSize="8192"

maxThreads="150" minSpareThreads="25" maxSpareThreads="75"

enableLookups="false" disableUploadTimeout="true"

acceptCount="100" scheme="https" secure="true"

clientAuth="false"

keystoreFile="/root/.keystore" ### add this line

keystorePass="put-your-password-here" ### add this line – this is the password from the certificate creation command

sslProtocol="TLS" />

With these changes now configured, we need to restart the Tomcat application server.

sudo /etc/init.d/tomcat5.5 restart

Now we’ll enable the new echart interface.

cd $HOME/src/oscar_source/oscar_mcmaster/database/mysql

java -cp .:/usr/local/tomcat/webapps/oscar/WEB-INF/lib/mysql-connector-java-3.0.11-stable-bin.jar importCasemgmt /usr/local/tomcat/oscar.properties

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;

quit ### gets you out of mysql

The DrugRef source resides on a different code branch from the main OSCAR system. We will now download the subsystem.

cd $HOME/src/oscar_source

cvs -d:pserver:anonymous@oscarmcmaster.cvs.sourceforge.net:/cvsroot/oscarmcmaster login

cvs -z3 -d:pserver:anonymous@oscarmcmaster.cvs.sourceforge.net:/cvsroot/oscarmcmaster co -P -D "2009-07-20 23:59:59" drugref

cvs -d:pserver:anonymous@oscarmcmaster.cvs.sourceforge.net:/cvsroot/oscarmcmaster logout

We need to create some directories for DrugRef and move the code into them.

sudo ln -s /usr/lib/postgresql/8.3 /usr/local/pgsql

sudo mkdir /usr/local/DPD

sudo mkdir /usr/local/drugref-ca_1_5

sudo cp -r $HOME/src/oscar_source/drugref/drugref2/DPD/* /usr/local/DPD

sudo cp -r $HOME/src/oscar_source/drugref/drugref2/drugref-ca_1_5/* /usr/local/drugref-ca_1_5

We now need to give ownership of these files and directories to the postgres account.

sudo chown -R postgres:postgres /usr/local/DPD

sudo chown -R postgres:postgres /usr/local/drugref-ca_1_5

We will log into the postgres account for the next section, but first, we will need to set a password for the account.

sudo passwd postgres

su - postgres

We need to enable the execution bits on a couple of scripts.

cd /usr/local/DPD

chmod +x create_database.sh

chmod +x import_dpd.sh

The following command will create the database space for the DrugRef information.

./create_database.sh

The next command will download the latest drug database from Health Canada. This import script will take some time, so be patient (a good time to get a fresh coffee). You can ignore the ERROR: table "*****" does not exist CREATE TABLE messages.

./import_dpd.sh

We need to add a new first line to the DrugRef calling program to compensate for a python issue (see: http://www.python.org/dev/peps/pep-0263/). We also need to be specific about where the drug interactions plugins directory is.

First, edit the file:

vi /usr/local/drugref-ca_1_5/drugref_service.py

And now add as the very first line (including the sharp sign (‘#’)):

# coding: latin-1

Change the following line…

def __init__(self, plugindir="plugins", name = "Drugref Service", version="1.0"):

to reflect the current directory:

def __init__(self, plugindir="/usr/local/drugref-ca_1_5/plugins", name = "Drugref Service", version="1.0"):

Save the file. Finally when you get back to the terminal prompt, we will exit from postgres account.

exit

Now that you are back to your original shell, the last step is to start up the DrugRef subsystem.

We will configure the system so that it always will start when the server is turned on. To do this, we need to edit a system script.

sudo vi /etc/rc.local

Add the following line to /etc/rc.local (before the exit 0 line):

nohup su -c "/usr/bin/python /usr/local/drugref-ca_1_5/drugref_service.py >> /usr/local/drugref-ca_1_5/drug.log 2>&1 &" postgres

And run the script:

sudo /etc/rc.local

That’s it! Your base OSCAR package is configured.

Trying It Out

We are now ready to log into OSCAR for the first time.

To test the connection, open your web browswer and go to your the web address of your server as shown below. You should see the OSCAR login page.

In the specific example below, replace the IP address of the example URL with the IP address of your server. To find the IP address of your server you can run the command "ifconfig" from the shell that you have been using to configure the system.

https://192.168.2.200:8443/oscar/

Your connection to the OSCAR server is encrypted.

Your browser may complain about your unofficial or uncertified certificate. You can ignore these warnings and avoid them in the future by installing the certificate on your workstation. The instructions for doing this is browser specific and beyond the scope of this document.

The default login parameters for OSCAR is as follows:

User Name: oscardoc

Password: mac2002

2nd Level Passcode: 1117

The first thing you will need to do once you log in, is change your passwords from the defaults. The primary password is changed via the Pref -> Change Your Password menu. The secondary password is changed via the Admin -> Search/Edit/Delete Security Records menu.

Configure Your Backup

There are a number of ways to automate your backup. A few areas will need to be considered:

the database
the properties file
the document upload directory
the eforms directory

My recommendation is to automatically backup the database nightly, then use rsync to move all the files, including the database dump to a remote machine.

First, create a database backup directory, and change the permissions so that only the root user can read the contents.

sudo mkdir /usr/local/backups

sudo chown tomcat55:nogroup /usr/local/backups

sudo chmod 755 /usr/local/backups

Now we will create a script that we can use to backup the database and create an archive of all the dynamic files on the system. As the archive file of the uploaded files will become quite large over time, we’ll only keep two copies on hand at any given time. You can, of course, configure your system to keep more if you like.

First, we will create the file:

sudo vi /usr/local/backups/backupOSCAR.sh

In this file, put the following lines (replacing the ****** with your actual mySQL database password):

#!/bin/sh -e

#

/usr/bin/mysqldump –add-drop-table -uroot -p****** oscar_mcmaster > /usr/local/backups/backupOSCAR-`date +%F`.sql

/bin/gzip -f /usr/local/backups/backupOSCAR-`date +%F`.sql

/bin/mv /usr/local/backups/backupOscarFiles.tar.gz /usr/local/backups/backupOscarFiles.older.tar.gz

/bin/tar cfz /usr/local/backups/backupOscarFiles.tar.gz /usr/local/tomcat/webapps/OscarDocument/oscar_mcmaster /usr/local/tomcat/oscar_mcmaster.properties

Make this file executable.

sudo chmod 700 /usr/local/backups/backupOSCAR.sh

We’ll configure Ubuntu to run the command every day. This is done by creating a cron job for the script we just made. Run the following command:

sudo crontab -e

And add to the existing file an entry so that the command looks like below:

# m h dom mon dow command

04 04 * * * /usr/local/backups/backupOSCAR.sh

You’ve now configured a daily backup of the mySQL OSCAR database. This backup will run at 4 minutes after 4 am, each morning. Each backup file will be created in the /usr/local/backups directory and will be time stamped based on the day it was created.

You will be able to see the contents of the backup directory with the command:

sudo ls /usr/local/backups

These backup files are also viewable/downloadable via the Admin->oscarDatabase/Document Download tab from within OSCAR.

To restore OSCAR from a backup file, you run this command (once again, inserting your own password in lieu of the asterisks, and also adjusting the timestamp for the appropriate backup file from your own directory):

sudo zcat /usr/local/backups/backupOSCAR-2008-11-20.sql | mysql -uroot -p****** oscar_mcmaster

Finally, lets move the backup files, and the backup database to a remote machine. This is accomplished by running the following command, and replacing username with a valid username for the remote machine, and replacing domainname with the FQDN or IP of the remote host:

sudo rsync -azvv -e ssh /usr/local/backups username@domainname:backups

You have now completed a full installation of OSCAR. Keep reading for hints on what to do next.

Getting Started With OSCAR

Now that OSCAR is installed, there are a number of activities that you will need to perform to get the most out of your new CMS. Some of these tasks may include:

add users and configure their security and optionally their schedules
configure your clinic information
import your patient demographic records
localize your billing templates and update the system to the lastest fees schedule
configure electronic access to your labs
configure your prescription pad
add some forms and eforms

Many of these activities are intuitive to configure and most are described in the user guide which is available on the OSCAR Canada web site.

I will help you through a couple simple tasks to get you started.

Configuring Forms

Log into the OSCAR server as oscardoc.

Select from the menu Admin -> Select Forms. This will open a window which allows you to add and remove the forms that are available via the patient’s Encounter window.

Highlight Discharge Summary from the Selected Forms list, and click Delete. Add the following forms from the All Available Forms list:

Annual
Annual V2
CHF
Growth 0-36m
Growth Charts
ImmunAllergies
Lab Req 2007
Mental Health
MMSE
PeriMenopausal
Risk Assessment
Rourke
Rourke2006
Self Efficacy
T2Diabetes
Vascular Tracker

To finish your selection, click the Close button.

These forms will now be viewable via the Encounter page of each patient.

Enabling Flowsheets

OSCAR supports a number of flowsheets, including:

INR
Hypertension
HIV
Diabetes

These flowsheets are enabled by configuring the disease registry. First, select Admin -> Customize Disease Registry Quick List -> Edit Quick List -> default.

Then you enter each of the icd9 codes for the following items and select Add (select Close when you are finished):

Atrial Fibrillation (code: 42731)
Diabetes Mellitus (code: 250)
Essential Hypertension (code: 401)
Human Immuno Virus Dis (code: 042)
HX-VEN Thrombosis/Embols (code: V1251)
Long-Term Use Anticoagul (code: V5861)

And now, to enable a flowsheet for a specific patient, you will select from the patient’s Encounter -> Dx Registry -> Quick List window the appropriate condition. The appropriate flowsheet will now be enabled on the Encounter page (you will need to refresh/reload the Encounter page to see the Flowsheet under the Measurements heading.