(Historical Reference) Installation of OSCAR 15 on Ubuntu 14.04 by DEB

Installation of OSCAR made easy by deb. These instructions reliably produce a stable working OSCAR 15 server on an existing Ubuntu 14.04 server.  For new servers see alternate instructions for OSCAR 15 on Ubuntu 16.04.

Preface

This basic install is adequate for a local install of OSCAR with scripted encrypted backups and Secure Socket Layer technology.   Network and systems management including but not limited to firewalls, securing your network to safely allow external access to OSCAR, remote administration,  disaster planning are all important topics that are not handled here.

Document Version History

• v1.0 – initial OSCAR 14 version published to oscarmanual.org – Feb 10, 2015
• v1.1 – added instructions for 32 bit wkhtmltopdf (thanks Earl) – Feb 18, 2015
• v1.2 – initial OSCAR 15 version published to oscarmanual.org – April 3, 2015
• v1.3 – switched to recommending Oracle Java 7 as per development team – May 15, 2015
• v1.4 – updated to reflect newer versions of wkhmltopdf – Jan 15, 2016
• v1.5 – updated to reflect newer upgrade information – Feb 10, 2016
• v1.5 – added pgpgpg as dependency needed for export – Feb 22, 2016
• v1.6 – altered description of deb naming convention to current – Feb 24, 2016
• v1.7 – added missing dependencies to the apt-get instructions – Mar 4, 2016
• v1.8 – changed migration to first go through OSCAR 12_1 build 568 or newer – Mar 11, 2016
• v1.9 – updated instructions to add unattended upgrade and migration of OscarDocument to /usr/share/oscar-emr/OscarDocuments – Mar 16, 2016
• v1.10 – Java 7 has reached end of life. We are now recommending Java 8 – Mar 22, 2016
• v1.11 – moved migration instructions to its own page – Mar 31, 2016 
• v1.12 – changed Java 8 naming convention to match web upd8 – April 29, 2016 
• v1.13 – added information on MariaDB 10 and MySQL v 5.7 – June 30, 2016 
• v1.14 – added hardware information – July 8, 2016 
• v1.15 - added note about OpenJDK being installed - Dec 31,2016
• v1.16 - added note about downgrading by deb requiring clearing of the Tomcat cache - Jan 26, 2017

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

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 ( 14.04 LTS ) or Mint ( 17 LTS ) both are supported to April 2019.  We recommend *full disk encryption*, if you are able to manually provide the password after a power outage or reboot.  See the reference installation instructions for details for Ubuntu 16.04.  The OSCAR_15 deb also installs on Debian Jessy (with Oracle Java 8 and either MariaDB 10 or MySQL 5.5).
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 supported infrastructure.  Ubuntu 14.04 is supported to April 2019.  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 64 bit machines you can download the JAVA 8 Java SE fromhttp://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html

sudo tar -xzvf jdk-8u101-linux-x64.tar.gz
sudo mv ./jdk1.8.0_101/ /usr/lib/jvm/
sudo ln -s /usr/lib/jvm/jdk1.8.0_101 /usr/lib/jvm/java-8-oracle

You can use a newer update but DO NOT vary from that naming of the link as Tomcat will be looking to /usr/lib/jvm/java-8-oracle to find JAVA

Then edit your /etc/profile by adding these lines to the bottom of the file

export JAVA_HOME=/usr/lib/jvm/java-8-oracle export PATH=$JAVA_HOME/bin:$PATH

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.  The version of wkhtmltopdf that is hosted by Ubuntu 14.04 ( 0.9.9-4) is no longer supported and is reported by the developers as having multiple security and other bugs.  Download the latest official wkhtmltopdf from http://wkhtmltopdf.org/downloads.html.

If you are installing on Ubuntu 14.04 or Mint 17 64 bit you will use something like the following

wget http://download.gna.org/wkhtmltopdf/0.12/0.12.3/wkhtmltox-0.12.3_linux-generic-amd64.tar.xz sudo tar vxf wkhtmltox-0.12.3_linux-generic-amd64.tar.xz
sudo rsync -vlr wkhtmltox/* /usr/local/
sudo ln -s /usr/local/bin/wkhtmltopdf /usr/bin/wkhtmltopdf
sudo ln -s /usr/local/bin/wkhtmltoimage /usr/bin/wkhtmltoimage

If you don't want to use the symlinks merely adjust your path.

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)

to test that its output can support the usual options that OSCAR needs run the following and then 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

For troubleshooting check that you have all the dependencies (zlib, fontconfig, freetype, X11 libs including libX11, libXext, libXrender)

The version of wkhtmltopdf that is hosted by Ubuntu 14.04 ( 0.9.9-4) is no longer supported and is reported by the developers as having multiple security and other bugs.

Tomcat 7 and Others

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

Use Tomcat 7 as its tested and stable.  Initial testing suggests Tomcat 8 will work in the future, but the DEB is currently aligned to Tomcat 7.

NOTE: one of these components installs the older OpenJDK 7 version. This may not matter to OSCAR as the DEB will point Tomcat to use Oracle Java 8, but elsewhere you will be using OpenJDK 7 unless you run the 'update-alternatives' to point to Oracle Java 8 (recommended).

sudo update-alternatives --config java

MySql 5.5

Your specific CMS data, profiles, and clinical information will all be stored in the MySQL database. 

On Ubuntu 14.04 and Mint 17 you can get MySQL 5.5 (the version is important) with:

sudo apt-get install mysql-server libmysql-java

This installation sequence will ask you for a secure password for the database server as below. 

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

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.

NOTE MySQL 5.6 and 5.7 (the latter the default MySQL in Ubuntu 16.04) are NOT supported.  Consider MariaDB 10 instead.  You may get MySQL 5.7 to work by altering the installation by removing STRICT_TRANS_TABLES SQL mode from my.cnf but this is not fully tested.

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 is recommended. 
• If you are experiencing bugs, try upgrading to a higher number build (the last 3 digits of the deb's name) that incorporates the fix.   
• Note that only the original release has been formally QA'd for production and while many bugs have been fixed in newer builds, 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-50~502.deb

 Now simply run the package and follow the instructions

sudo dpkg -i oscar_emr15-50~502.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

You can freely upgrade by installing a different OSCAR deb over an existing one within a given OSCAR version

Note that for a deb downgrade as newer files will persist in cache you must manually delete the current oscar.war prior to running the older deb to roll back the installation.

Install OSCAR Step 1 

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

Start by providing the MySQL/MariaDB password you assigned.

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

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.

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

 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

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

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.  Note that if the newer version you install appears unstable you can downgrade the installation by running the older deb to overwrite the new.

sudo dpkg -i oscar_emr15-38~428.deb