4.2.1 oscar_emr12.1.1.deb Installation

Preface

This basic install is adequate for a local install of OSCAR with encrypted backup script and Secure Socket Layer technology.  Note that OSCAR 12.1 is no longer being supported and these instructions are provided for reference only.  Please use instructions for a newer version elsewhere on this website.

Document Version History

• v1.0 – initial public release to oscarmanual.org – August 28, 2012
• v1.1 – Updated to reflect Release Candidate 20 – Sept 12, 2012
• v1.2 – Updated to reflect General Release build 24 – Sept 30, 2012
• v1.3 – Updated to reflect General Release build 25 – Oct 1, 2012
• v1.4 – Java installation instructions changed to sun-java6 – Oct 6, 2012
• v1.5 – Updated to release 35 which includes backup script setup – Nov 25, 2012
• v1.6 – Updated to release 45 which includes some database fixes – Dec 15, 2012
• v1.7 – Updated to release 48 which optionally includes SSL setup – Dec 30, 2012
• v1.8 – Updated to release 61 with deb script 2.5 which includes automated SSL setup – Jan 12, 2013
• v1.9 – Updated OAB to include --no-check-certificate and possible edit - Feb 6, 2013
• v2.0 – Updated to release build 102 which contains an updated drugref database - April 2, 2013
• v2.1 – Updated to release build 114 which contains an updated drugref database - April 16, 2013
• v2.2 – Recommended changing my.cnf settings to use InnoDB engine and utf8 encoding as defaults - April 24, 2013
• v2.3 – Reverted to 2.1 and updated references to build 120 – April 25, 2013
• v2.4 – As OAB is currently broken, added manual Java installation instructions – July 28, 2013
• v2.5 – Added instructions to point Tomcat to the preferred Java – Aug 2, 2013
• v2.6 – Updated references to build 199 – Aug 9, 2013
• v2.7 – Updated java instructions – Aug 30, 2013
• v2.8 – Updated instructions for 12.1.1 – Oct 28, 2013
• v2.9 – Added troubleshooting for Patching database tread stack error for deb version 44  – Jan 18, 2014
• v3.0 – Updated screenshots and instructions to reflect late 12.1.1 screens  – Feb 16, 2014
• v3.1 – Updated instructions to reflect Ubuntu 14.04.2 and the latest deb  – July 26, 2015
• v3.2 - Added note about dpkg changes breaking the deb updates - Aug 25, 2015
• v3.3 - Added note about end of life and updated instructions to build 576 - May 16, 2016
• v3.4 - Updated instructions to the final DEB version build 580 - Aug 10, 2016
• v3.5 - Added some Java advice for BC Teleplan - Oct 4, 2016

Prerequisites

It is assumed that

1. You have the time.  Allow a minimum of 5 minutes to install Ubuntu, 7 minutes to install the infrastructure packages, and a final 2 minutes to install OSCAR itself.  Downloading the software adds additional time and is dependent on your connection and can take 20 additional minutes @150KB/s.
   
2. You are using suitable hardware.  While the OSCAR server reportedly boots on a Raspberry pi ARM with 512MB, for production use we recommend a pair of new $500 desktops with 4GB RAM for 1-3 MD's increasing to server specific designed machines with 16GB for 7+ MD's.  The author runs Intel Xeon server with 32GB RAM with a i7 backup server with 16GB RAM for a database that is 6GB in size and has 20 users in a virtualised environment.
   
3. You have installed a Debian based Linux (tested on Ubuntu 10.04+, Mint 9+, Debian Wheezy)
   We recommend the 64 bit LTS version of Ubuntu ( 14.04 LTS ) with full disk encryption.  
4. You have a basic level of Linux knowledge and you can open a Linux terminal
5. You can cut and paste EXACTLY the following instructions (These instructions are sensitive to spelling packages and order.  Vary only after you have a working server )
   

NOTE: Firefox will copy with Control+C while a Linux terminal requires Shift+Control+V for paste

Installing The Infrastructure Packages

If you have previously installed OSCAR you have already done this...... so skip to the Installing OSCAR section.

Java

Oscar works the best with Oracle-Sun-Java, and we have plenty of experience with Oracle-Sun-Java 1.6.0 so this is preferred unless you are in BC. 

(Note BC teleplan as of late 2016 will actively refuse connections with Java 6, substitute Oracle Java 7)

Use your webbrowser to accept Oracle's terms and download from Oracle the 64bit Linux "compressed binary file" - it has a ".bin" file extension i.e.  "[java-version]-x64.bin" for 64bit. The following uses the file pattern for 64 bit Oracle Sun Java 6 update 45. 

sudo chmod +x jdk-6u45-linux-x64.bin
./jdk-6u45-linux-x64.bin

The JDK 6 package is thus extracted into ./jdk1.6.0_45 directory. - If you don't have the folder structure then make directories (mkdir).  Otherwise just move (mv) the JDK 6 directory to /usr/lib

sudo mkdir /usr/lib/jvm
sudo mkdir /usr/lib/jvm/java-6-sun
sudo mv ./jdk1.6.0_45/* /usr/lib/jvm/java-6-sun

Use the debian alternatives tool to register this java with the java  master group link

sudo update-alternatives --install "/usr/bin/java" "java" "/usr/lib/jvm/java-6-sun/bin/java" 1

Now get a choice of slave linked java's to activate

sudo update-alternatives --config java

This will give you options of java for your system.  If its a brand new Ubuntu 12.04 LTS system there will be nothing installed and you will get

However if you have more than one in this example you would pick 2 for Oracle Sun Java 6

There are 3 choices for the alternative java (providing /usr/bin/java).

Selection Path Priority Status
————————————————————
* 0 /usr/lib/jvm/java-6-openjdk/jre/bin/java 1061 auto mode
1 /usr/lib/jvm/java-6-openjdk/jre/bin/java 1061 manual mode
2 /usr/lib/jvm/java-6-sun/jre/bin/java 63 manual mode
3 /usr/lib/jvm/jdk1.7.0/jre/bin/java 3 manual mode

Press enter to keep the current choice[*], or type selection number: 2

Check the version of your new JDK 6 installation to confirm you have the version you want:

$sudo java -version
java version “1.6.0_45-b06”
Java(TM) SE Runtime Environment (build 1.6.0_45-b06)
Java HotSpot(TM) Client VM (build 20.10-b01, mixed mode) 

Tomcat 6

Tomcat 6 is needed to present OSCAR's webpages to your internet browser. Apt-get it, and some other dependencies

sudo apt-get install tomcat6 libmysql-java curl

The above in Ubuntu 14.04.2 will likely install java-7-openjdk as a "dependency" which will work, but may give you issues if you want to run integrator, MyOSCAR or other service.  To make sure that the Tomcat references your preferred Java, it should have

sudo nano /etc/default/tomcat6

and save

MySql

Your specific CMS data, profiles, and information will all be stored in the MySQL database.  You can use the latest version of MySQL obtained with:

sudo apt-get install mysql-server

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.  We recommend that you use numbers and letters in the password but do not use any of the symbols "#,!, &,*, (, ), / , \ and $" .

Remember this password as you will need it again later in the installation.

NOTE INTERNATIONAL INSTALLATION: For OSCAR in other languages READ the International Install section before proceeding any further

Installing OSCAR

Download the OSCAR deb package from Sourceforge.  http://sourceforge.net/projects/oscarmcmaster/files

wget http://sourceforge.net/projects/oscarmcmaster/files/Oscar%20Debian%2BUbuntu%20deb%20Package/oscar_emr12.1.2-76final585.deb

 Now simply run the package (try double clicking or the following command) and follow the instructions (Note this should uninstall any previous deb installed OSCAR, but will preserve its database)

sudo dpkg -i oscar_emr12.1.2-76final585.deb

The deb will provide feedback as to what it is doing however if you want more verbose details open another terminal window and invoke

tail -f /usr/share/OscarMcmaster/Oscar12.1.2install.log

Install OSCAR Step 1

New installs get the following install screens. (for upgrades see Appendix 1 below)

Start by providing the MySQL password you assigned when you installed MySQL.

 A screen will present and ask for your localization preference for billing.  If you are in BC pick BC and if you are in neither province (or not in Canada) then pick Other. The default is Ontario.

Optionally supply your particular phone prefix as a convenience for when patients are added to the demographics database.   This prefix can always be easily overwritten by front office staff as needed but saves keystrokes for them and reduces the opportunity for data entry errors.

In urban areas we suggest that you just add the area code, in rural areas it might be longer eg 705-6 for exchanges in Haileybury, New Liskeard, Latchford, Cobalt and Dymond

The fax support that this option configures is global and includes signature and some other support.  However to take full advantage of these features

1. You must use Firefox or Chromium for the newest Rich Text Letter to work (with signature and fax support)
   
2. You must have OSCAR configured as per Security Hardening including and specifically https on port 8443 for printing or faxing (the deb takes care of this for most cases)
   
3. Also Lan or Internet Faxing needs to be configured on your server for facsimile transmissions
   
4. While you can mouse sign the results are poorer than if you sign on another device (track pad etc)
   

This window will give you the option to populate the database with a demo patient with which to develop familiarity with OSCAR.  As mentioned you cam remove the demo data later with the  /usr/share/OscarMcmaster/undemo.sql

The Eyeform version is the most developed of the specialist interfaces possible with OSCAR.  The default is no.

Most people will want access to the intake form.

The new contacts interface is optional.

These settings, and more, can be changed manually through editing /usr/share/tomcat6/Oscar12_1.properties

Oscar/Tomcat need to restart whenever the properties file is modified to have the settings take effect.

and once installed don't forget to read the readme!

less /usr/share/OscarMcmaster/README.txt 

Trying It Out

At this point you have a fairly plain install. To test the connection, open your web browser and go to your the web address of your server.  While most browsers will work, for production use we recommend FireFox ESR version.  You should see the OSCAR login page with clicking on one of the following links.

In most cases you will be prompted to reach your SSL secured OSCAR server at https://localhost:8443/Oscar12_1

Make an exception for the certificate when Firefox complains that it is self-signed

Rarely if the installer was unable to configure SSL for you, the deb will warn you that your installation may be INSECURE but will work at http://localhost:8080/Oscar12_1

In the latter case, if  you had not already done so please manually secure your Oscar server using instructions for Security Hardening

 The default login parameters for OSCAR are on the screen and duplicated below as follows:

User Name: oscardoc
Password: mac2002
2nd Level Passcode: 1117

***NOTE THAT FOR SECURITY THESE CREDENTIALS ARE SET TO EXPIRE A MONTH AFTER INSTALLATION SO YOU SHOULD SET UP YOUR OWN LOGIN NOW ****

If you can login then you have successfully installed a plain OSCAR and you can start playing with it.

Appendix 1 Upgrading from older deb installations

Note that this deb will replace (or attempt to replace) any older deb installed program if it can find one

(it will NOT overwrite the previous database, but like upgrading firefox, the previous program itself will be gone)

Please note that any upgrade of production essential systems, requires a prior backup... which is good practice anyway

 

 Allow for a minute or two for the deb to run.  Once Tomcat restarts you will be given back the prompt.

Troubleshooting

• If Tomcat is picking up the wrong JVM you can force the one you want by editing /etc/tomcat6 to specify JAVA_HOME
• If you get an error  Patching database to latest schema, check /usr/share/OscarMcmaster/Oscar.err it might be a Thread Stack overrun,  comment out the entry in my.cnf
  
• The dpkg program was updated at version 1.15.6 (Ubuntu 10.04).  If you try to use a new deb with an older version of dpkg, it will fail with:  dpkg-deb: file `oscar_emr12.1.2-68general494.deb' contains ununderstood data member data.tar.xz     , giving up.  You will need to update dpkg to a newer version. The easiest way is to upgrade your version of Ubuntu to 12.04 or greater.