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 email@example.com.
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
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.
sudo apt-get install postgresql-8.3 python-pgsql
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.
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.
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
cvs -d:pserver:firstname.lastname@example.org:/cvsroot/oscarmcmaster login
cvs -z3 -r -d:pserver:email@example.com:/cvsroot/oscarmcmaster co -r RELEASE_9_06 -D “2009-07-20 23:59:59” oscar_mcmaster
cvs -d:pserver:firstname.lastname@example.org:/cvsroot/oscarmcmaster logout
It will take a few minutes for the source code to download. Afterwards, compile OSCAR.
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 your mysql root password. Remember this password as it will be required to administer the database.
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.
If you have not set your mysql root password, ( default install of mysql does not have a password for the root user ) you will get a ERROR 1045 (28000): Access denied for user ‘root’@’localhost’ (using password: YES) the above scripts to populate your database require a password, you should also have a password on your root database so no one else can access the data ( good security policy )
If you have never set a root password for MySQL, the server does not require a password at all for connecting as root. To setup root password for first time, use mysqladmin command at shell prompt as follows:
$ mysqladmin -u root password NEWPASSWORD
However, if you want to change (or update) a root password, then you need to use following command:
$ mysqladmin -u root -p’oldpassword’ password newpass
For example, If old password is abc, and set new password to 123456, enter:
$ mysqladmin -u root -p’abc’ password ‘123456’
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
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)
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″
acceptCount=”100″ scheme=”https” secure=”true”
keystoreFile=”/root/.keystore” ### add this line
keystorePass=”put-your-password-here” ### add this line – this is the password from the certificate creation command
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.
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.
cvs -d:pserver:email@example.com:/cvsroot/oscarmcmaster login
cvs -z3 -d:pserver:firstname.lastname@example.org:/cvsroot/oscarmcmaster co -P -D “2009-07-20 23:59:59” drugref
cvs -d:pserver:email@example.com:/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.
chmod +x create_database.sh
chmod +x import_dpd.sh
The following command will create the database space for the DrugRef information.
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.
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:
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.
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:
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.
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
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):
/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.
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 V2
- Growth 0-36m
- Growth Charts
- Lab Req 2007
- Mental Health
- Risk Assessment
- Self Efficacy
- Vascular Tracker
To finish your selection, click the Close button.
These forms will now be viewable via the Encounter page of each patient.
OSCAR supports a number of flowsheets, including:
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.