4.1.0.1 DEPRECATED Installation of 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. 

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
• v1.4 - added sudo to tee for webuptod8 Oracle java place - April 10, 2017
• v1.5 - reverted to OpenJDK 8 - April 24, 2017
• v1.6 - added information about troubleshooting wkhtmltopdf  Dec 8, 2017
• v1.7 - altered to make these the REFERENCE instructions  Dec 20, 2017
• v1.8 - added --disable-smart-shrinking flag to wkhtmltopdf Feb 20,2018
• v1.9 - added information about the developer maintained qt patched wkhtmltopdf  Oct 27, 2018
• v2.0 - changed Java recommendation to Open JDK 8  Nov 6, 2018
• v2.1 - Added firewall instructions Feb 10, 2019
  

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. We do not assume you are using a virtual machine (VM) but we recommend it for enterprise level equipment.  A virtualization environment (hypervisor) allows you to install one or more servers as virtual machines (VM) to improve security and ease maintenance.
   
4. 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 strongly recommend *full disk encryption*, if you are able to manually provide the password after a power outage or reboot.  If you are using a VM the password can be provided remotely.
   
5. You have a basic level of Linux knowledge and you can open a Linux terminal
6. You can cut and paste EXACTLY the following instructions (These instructions are sensitive to spelling packages and order. )
   

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

VERSION NOTES: OSCAR 15 has previously been built against Oracle Java 8, which, as of Jan 2019, is no longer open source.  Any "Business, Commercial or Production use" now requires a commercial license.  As a result we now endorse Open Java.  Many OSCAR instances are already running successfully on Open JDK 8 which is a drop in replacement.

NOTE that Open JDK Version 8 is the *only* version supported with current OSCAR 15 builds.    We provide details for the binary packaged for the Ubuntu distro.

Open JDK 8

Open JDK as packaged by Ubuntu has advantages as it is easier to install, it has unlimited security patch already installed, and has automated updates.

sudo apt-get install openjdk-8-jre

# java -version
openjdk version "1.8.0_121"
OpenJDK Runtime Environment (build 1.8.0_121-8u121-b13-)ubuntu1.16.04.2-b13)
OpenJDK 64-Bit Server VM (build 25.121-b13, mixed mode)

wkhtmltopdf

VERSION NOTES: OSCAR uses wkhtmltopdf to print some pdf content. You can use the apt install method for the repository version but it has an non listed dependency on X11, ie a desktop environment.  If you are deploying a headless server you need the version that the wkhtmltopdf maintainers  use.

Use the following to install version 0.12.2.4-1 or newer in a machine that has a GUI

sudo apt-get install wkhtmltopdf

wget https://github.com/wkhtmltopdf/wkhtmltopdf/releases/download/0.12.5/wkhtmltox_0.12.5-1.xenial_amd64.deb
dpkg -i wkhtmltox_0.12.5-1.xenial_amd64.deb

wkhtmltopdf -V
wkhtmltopdf 0.12.5 

wkhtmltopdf -s Letter -T 10mm -L 8mm -R 8mm --print-media-type --disable-smart-shrinking / test.pdf

Debugging suggestions:

• "QXcbConnection: Could not connect to display" is the error you get when running wkhtmltopdf in a headless server.   Short of installing the full X11 you can use the Ubuntu version and to install Xvfb (X virtual framebuffer) which is a lightweight virtual server implementing the X11 display protocol.

apt-get install xvfb
echo -e '#!/bin/bash\nxvfb-run -a --server-args="-screen 0, 1024x768x24" /usr/bin/wkhtmltopdf -q $*' > /usr/bin/wkhtmltopdf.sh
chmod a+x /usr/bin/wkhtmltopdf.sh
ln -s /usr/bin/wkhtmltopdf.sh /usr/local/bin/wkhtmltopdf

Tomcat 7

Java uses Tomcat to present OSCAR's webpages to your internet browser.  Apache has not yet announced when Tomcat 7 will be end of life but will give a years notice.

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.  UFW (Uncomplicated Firewall) is a program for managing a netfilter firewall.  Apt-get them

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

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

For a headless server you can test locally with lynx, a text-based web browser.  Otherwise test from another machine by replacing localhost with the IP of the server.

If you don't get a welcome screen then it is likely that Tomcat is not picking up your java.

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.

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-76~714.deb

 Now simply run the package and follow the instructions

sudo dpkg -i oscar_emr15-76~714.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)

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.  You can remove the demo data later with the following (replace ****** with your MariaDB/Mysql password).

mysql -uroot -p******* oscar_15 <  /usr/share/oscar-emr/undemo.sql

While customary production settings will be applied, they can be changed manually through editing /usr/share/tomcat7/oscar.properties in your favorite text editor.

Note that 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 with an "insecure connection" error as the certificate is self-signed.   As it is your installation you can safely click on "Advanced" and set an 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 with default oscar.properties settings

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

Finishing Up

There are many additional settings that you can do to your server that I will not document.  However a firewall is so important that we should configure it even if your server is behind an enterprise router.

Uncomplicated Firewall

Set up the default rules to allow all outgoing connections and deny all incoming

sudo ufw default deny incoming
sudo ufw default allow outgoing

Now set the firewall to allow incoming connections of all the ports you need

• Users will access OSCAR on port 8443
  
• if you are using SSH to access your sever you need to allow your port (usually 22) *before* you enable the firewall

sudo ufw allow 8443
sudo ufw allow 22

8080 will be blocked to external access from the default rules (it is still needed locally for drugref) but I like to explicitly close it with

sudo ufw close 8080

Enable the firewall

sudo ufw enable

Check the settings

sudo ufw status

Upgrades and Downgrades

Upgrades

Migrations from OSCAR 12_1 should use the instructions in 4.1.1.  However upgrades in the OSCAR 15 release series can be run unattended.  Merely use the same syntax for upgrade as for installation and both the program and the database will be updated.  You can do this safely as you will not break your installation.  However as may break functionality with a new bug, be prepared to revert by downgrading.

sudo dpkg -i oscar_emr15-69~688deb

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