(Historical Reference) Installation of OSCAR 15 on Ubuntu 16.04

Owned by Marc Dumontier
Last updated: Oct 12, 2018 by Raymond Rusk
6 min read

This page has been imported from http://www.oscarmanual.org and has not yet been reviewed by OSCAR EMR.

Preface

This basic install is adequate for a local install of OSCAR with scripted encrypted backups and Secure Socket Layer technology. 

Document Version History

  • v1.0 – initial OSCAR 15 version published to oscarmanual.org – June 30, 2016
  • v1.1 – simplified instructions for Java to use a PPA – July 8, 2016
  • v1.2 – added mariaDB password – Jan 26, 2017
  • v1.3 – reworked as the Reference installation instructions – Feb 3, 2017

 copyright © 2012-2016 by Peter Hutten-Czapski MD under the Creative Commons Attribution-Share Alike 3.0 Unported License


Contents

  1. Preface
    1. Document Version History
  2. Prerequisites
  3. Installing The Infrastructure Packages
  4. Installing OSCAR
  5. Trying It Out
  6. Upgrades and Downgrades

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.  Note that upgrading from OSCAR 12_1 will take at least a few hours depending on size of your data.
  2. You are using suitable hardware.  While the OSCAR server runs any recent CPU with 1GB RAM, 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.  Server spec machines offer component redundancy and improved reliability that is an advantage in any setting, but all systems need contingency plans for hardware failure. 
  3. You have installed a current 64 bit LTS version of Ubuntu ( 16.04 LTS ) or Mint ( 18 LTS ) both are supported to April 2021.  We recommend *full disk encryption*, if you are able to manually provide the password after a power outage or reboot.  
  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. )

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

Installing The Infrastructure Packages

EVEN IF YOU HAVE INSTALLED OSCAR BEFORE you need to install the latest infrastructure.  OSCAR 15 requires SPECIFIC versions of the infrastructure packages.  If you are installing OSCAR for the first time you should follow these instructions to the *letter*, as stability and reliability is tested against these defaults.

JAVA 8 (Oracle)

The development team feel that the Oracle implementation of Java 8 should be used for optimal security and to allow leverage of new language features in Java 8 in upcoming OSCAR builds. For simplicity use the webupd8team PPA to obtain it.

Paste this lines on your root prompt and accept the Oracle License terms:

sudo echo "deb http://ppa.launchpad.net/webupd8team/java/ubuntu xenial main" | tee /etc/apt/sources.list.d/webupd8team-java.list
sudo echo "deb-src http://ppa.launchpad.net/webupd8team/java/ubuntu xenial main" | tee -a /etc/apt/sources.list.d/webupd8team-java.list
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys EEA14886
sudo apt-get update
sudo apt-get install oracle-java8-installer

And that's it, Oracle Java 8 should now be installed and you should get automatic updates for future Oracle Java 8 versions, under Debian.

Test if desired (your build number may be slightly different):

# java -version
java version "1.8.0_101"
Java(TM) SE Runtime Environment (build 1.8.0_101-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.101-b13, mixed mode)

NOTE: While other Java's will work, including, on light testing, Open JDK 8, they are not suggested

wkhtmltopdf

OSCAR uses wkhtmltopdf to print some pdf content.  Use the following to install version 0.12.2.4-1 or newer

sudo apt-get install wkhtmltopdf

With the following line you can check if you can check its version (sample correct version output shown). 

wkhtmltopdf -V
wkhtmltopdf 0.12.3 (with patched qt)

Test if desired.  The following are the usual options that OSCAR needs, check the resultant pdf to see that it displays.

wkhtmltopdf -s Letter -T 10mm -L 8mm -R 8mm --print-media-type http://oscarmanual.org test.pdf

Tomcat 7

Java uses Tomcat to present OSCAR's webpages to your internet browser.  Unzip is used to decompress zip files.  Curl is an internet file transfer utility.  Pgpgpg is optionally used by OSCAR to encrypt charts for export.  Apt-get them

sudo apt-get install tomcat7 libtomcat7-java unzip curl pgpgpg

Test if desired by pointing your browser at http://localhost:8080

VERSION NOTES: Use Tomcat 7 as its tested and stable.  Initial testing suggests Tomcat 8, which is also available in the Ubuntu repositories, will work in the future.

MariaDB 10

OSCAR uses this database to store your data. You can use the latest version of MariaDB obtained on Ubuntu 16.04 with:

sudo apt-get install mariadb-server mariadb-client libmysql-java

This installation will need to be secured with the following (follow the scripts suggested defaults)

IMPORTANT  use numbers and letters in the root password but do not use any of the symbols "#,!, &,*, (, ), / , \ and $" .

sudo mysql_secure_installation

Test if desired by logging into the MariaDB server with the following command

and you should get something like:

$ sudo mysql -uroot -p
Enter password: 
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 65
Server version: 10.0.25-MariaDB-0ubuntu0.16.04.1 Ubuntu 16.04

Copyright (c) 2000, 2016, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]>

Then you will want OSCAR to be able to login without using the plugin to pass linux root credentials

MariaDB [(none)]> use mysql;
MariaDB [mysql]> update user set plugin='' where User='root';
MariaDB [mysql]> flush privileges;
MariaDB [mysql]> quit

VERSION NOTES: While OSCAR previously used MySQL, MySQL 5.7 does not natively support OSCAR 15 without modification. The MariaDB database is a binary compatible fork of MySQL.  Its developers (who founded MySQL) claim that it is faster than MySQL and better optimized.  Advanced cluster replication is available but varies from MySQL.


Installing OSCAR

Download the OSCAR deb package from Sourceforge.  There are several to choose from. 

The naming format is oscar_emr{OSCAR_VERSION}-{DEB_VERSION}~{BUILD}.deb

  • OSCAR 15 is a running release, the latest file will do fine
  • If you are experiencing bugs, try either upgrading to a higher number build (the last 3 digits of the deb's name) that incorporates the fix, or downgrading to an earlier deb that does not have the problem.
  • Note that stability is not necessarily improved by a higher build number.

All are at http://sourceforge.net/projects/oscarmcmaster/files


Note that the latest filename or path may be slightly different than exampled below.   

wget http://sourceforge.net/projects/oscarmcmaster/files/Oscar%20Debian%2BUbuntu%20deb%20Package/oscar_emr15-52~513.deb

 Now simply run the package and follow the instructions

sudo dpkg -i oscar_emr15-52~513.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/oscar-emr/Oscar15install.log


Install OSCAR Step 1 

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

OSCAR setting MySQL password

Start by providing the MySQL/MariaDB password you assigned.

OSCAR Demo

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/oscar-emr/undemo.sql

While standard settings will be applied, they can be changed manually through editing /usr/share/tomcat6/oscar.properties

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

Install OSCAR Step 2

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


You can read the readme!

less /usr/share/oscar-emr/README.txt


Trying It Out

At this point you have a fairly plain install. To test the connection, click on the link displayed on the output above or open your web browser and type in the address manually.  While most new browsers (Chrome, Safari 9+ etc) 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/oscar .

Firefox will complain at this point that the certificate is self-signed.  As it is your installation you can safely click on "I understand the Risks" and make the exception and proceed to your OSCAR server.

Firefox Exception

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/oscar

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

14 Login

 The initial login parameters for OSCAR are as follows:

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

When you login then you will be presented with a one time password reset for security purposes
8 characters upper and lower case numbers and symbols are  required


14 Change password

You have successfully installed a plain OSCAR and you can start playing with it.

Upgrades and Downgrades

Upgrades 

Upgrades from OSCAR 12_1 must use the Migration instructions in Appendix 1.  However upgrades in the OSCAR 15 release series can be run unattended.  Merely use the same sytax for upgrade as for installation.  This can be done safely as you will not break the installation, although you may break functionality with a new bug so be prepared to revert by downgrading.

sudo dpkg -i oscar_emr15-38~428.deb

15 Upgrade Console

Downgrades

OSCAR 15 is a rolling release so that stability can fluctuate.  If the newer version you install appears unstable you can downgrade the installation by running the older deb to overwrite the new.  To delete the newer java classes so that the older ones fill you must first delete the oscar.war file manually 

sudo rm /var/lib/tomcat7/webapps/oscar.war

then run the older deb over the new one

sudo dpkg -i oscar_emr15-38~428.deb