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 – October 24, 2018
• v1.1 – Cleanups, including removal of Java 11 install as it doesn't work with OSCAR 15 – October 24-31, 2018
• v1.2 – Added Certbot documentation for Debs 89 and newer – November 1, 2018
• v1.3 – Fixed typo in certbot arguments, updated Java recommendations – November 23, 2018
• v1.4 – Added  notes for alternative binaries that provide java – January 19, 2019
• v1.5 – Added  firewall instructions – February 9, 2019
• v1.6 – Updated location of developers version of wktohtml – February 11, 2019

Prerequisites

It is assumed that

1. You have the time.  Allow a minimum of 14 minutes to install Ubuntu, 11 minutes to install the infrastructure packages, and a final 4 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 ( 18.04 LTS ) both desktop and server versions have been tested and are supported to April 2028.  We strongly recommend *full disk encryption*, if you are able to manually provide the password after a power outage or reboot.  You will need the "alternate server installer" to enable this setup for the server as the subiquity installer doesn't currently have the option to encrypt the LVM.
   
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

For production use we recommend the current REFERENCE instructions.  However as you are here we assume you are testing or are willing to take chances when you colour outside the lines.  Deviate from the instructions as you wish, and if its substantive deviation (and it works), please submit back your version.

As these are EXPERIMENTAL instructions, instructions for testing each step are included, and recommended.

First ensure that the Universe repository is available (if not already enabled, it isn't for subiquity installer Ubuntu 18.04 server) and update.

sudo add-apt-repository universe
sudo apt update
sudo apt upgrade 

OPTIONAL components

Note if you don't use Certbot the Deb installer will still configure a secure https connection for you with a self signed certificate.  Use Certbot it you have a fully qualified domain name (own your website name eg www.example.com).

Certbot

sudo apt install certbot

sudo certbot certonly --standalone -d FQDN

sudo ls /etc/letsencrypt/live/FQDN
cert.pem  chain.pem  fullchain.pem  privkey.pem  README

JAVA

OSCAR 15 was previously run with Oracle Java 8.  Oracle's licence now requires payment for "Business, Commercial or Production use" .  To remain open sourced ourselves we recommend you use Open JDK instead.

It has to be Java 8.  Java 9 and 10 are transient releases, don't install them.  Java 11 has just been released Sept 25, 2018 and is the next long term supported Java. Java 11 does NOT yet work with OSCAR 15.

Open JDK is provided by many binaries (look for ones that are Java SE compatible) including those provided by AdoptOpenJDK, Zulu, IBM, Corretto, J9, and those packaged by many Linux distros including Ubuntu.

a) UBUNTU Open JDK 8  < Most trusted option

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

sudo apt-get install openjdk-8-jre

$ java -version
openjdk version "1.8.0_191"
OpenJDK Runtime Environment (build 8u191-b12-0ubuntu0.18.04.1)
OpenJDK 64-Bit Server VM (build 25.191-b12, mixed mode)

Alternately you can use a binary from some of the other SE compatible versions such as Zulu (adjust the filename to latest)

$ wget https://cdn.azul.com/zulu/bin/zulu8.34.0.1-ca-jdk8.0.201-linux_amd64.deb
$ sudo dpkg -i zulu8.34.0.1-ca-jdk8.0.201-linux_amd64.deb
$ java -version
openjdk version "1.8.0_201"
OpenJDK Runtime Environment (Zulu 8.34.0.1-CA-linux64) (build 1.8.0_201-b10)
OpenJDK 64-Bit Server VM (Zulu 8.34.0.1-CA-linux64) (build 25.201-b10, mixed mode)

or the same for Eclipse J9

$ wget -qO - https://adoptopenjdk.jfrog.io/adoptopenjdk/api/gpg/key/public | sudo apt-key add -
$ sudo add-apt-repository --yes https://adoptopenjdk.jfrog.io/adoptopenjdk/deb/ 
$ apt-get update 
$ apt-get install adoptopenjdk-8-openj9

c) Or install many Java's and Configure the one you Want

If you have several versions of Java installed (and you may have installed one with the distro) you should check and change what /usr/bin/java points at with update-alternatives.

$ update-alternatives --config java
There are 4 choices for the alternative java (providing /usr/bin/java).

  Selection    Path                                               Priority   Status
------------------------------------------------------------
* 0            /usr/lib/jvm/zulu-8-amd64/jre/bin/java              1083400   auto mode
  1            /usr/lib/jvm/adoptopenjdk-8-openj9-amd64/bin/java   1081      manual mode
  2            /usr/lib/jvm/java-8-openjdk-amd64/jre/bin/java      1069      manual mode
  3            /usr/lib/jvm/java-8-oracle/jre/bin/java             1081      manual mode
  4            /usr/lib/jvm/zulu-8-amd64/jre/bin/java              1083400   manual mode

 in this example there are several JRE installed and Zulu is set as the default.

Early DEBS were coded to default to use Oracle Java 8 if present.  Recent OSCAR DEBS (oscar_emr15-94~851+) for new installs will pick the update-alternatives configured Java 8 at time of installation regardless of brand.  If you change the configured Java afterwards check that tomcat is started pointing to the correct JDK with the $JAVA_HOME setting in

$ sudo nano /etc/default/tomcat8

FOR J9 (untested) note that to use some of the more interesting garbage collection modes and some other J9 specific features, you should review the documentation at https://www.eclipse.org/openj9/docs/cmdline_migration/ and adjust the default $JAVA_OPTS in /etc/default/tomcat8 that the OSCAR deb configures into the ones you need for your particular JVM. 

Other Infrastructure Dependencies

wkhtmltopdf

OSCAR uses wkhtmltopdf to print some pdf content.  There are two versions of that program.  One is the version that you can apt install from an Ubuntu repository, which is feature restricted but usually gives good output.

If you are using a version of Ubuntu that has a GUI interface (desktop) it will be running X11 and you can use the following to install version 0.12.2.4-1 or newer.  Do not use this version if you are installing a headless server (see below instead)

sudo apt install wkhtmltopdf

wget https://downloads.wkhtmltopdf.org/0.12/0.12.5/wkhtmltox_0.12.5-1.bionic_amd64.deb
sudo apt install ./wkhtmltox_0.12.5-1.bionic_amd64.deb 
sudo ln -s /usr/local/bin/wkhtmltopdf /usr/bin/wkhtmltopdf

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

MariaDB 10

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

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

This installation has no initial password and 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
Enter current password for root (enter for none):
Set root password? [Y/n] 
New password: 
Re-enter new password: 
Remove anonymous users? [Y/n] 
Disallow root login remotely? [Y/n] 
Remove test database and access to it? [Y/n] 
Reload privilege tables now? [Y/n] 

Now there will only be the one root user set for MariaDB. 

OPTIONAL: If you want to install phpmyadmin (not described) as a MariaDB front end do it now before the next step.

Log into the MariaDB server with that 'root' user and provide the password you just set with the following command:

$ 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.1.34-MariaDB-0ubuntu0.18.04.1 Ubuntu 18.04

Copyright (c) 2000, 2018, 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 unix_socket plugin to pass Linux root credentials. 

The plugin prevents non system root users from logging in to MariaDB, but allows for root users to log in to MariaDB directly without a password. By removing the plugin everyone (including the non privileged tomcat user) can, and has to, sign into MariaDB by providing the MariaDB password.

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 and newer do 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.

Tomcat 8.5

Java uses Apache Tomcat to present OSCAR's webpages to your internet browser from the Universe repository.  There is no end of life for Tomcat 8.5 announced, but we expect that it will last to 2023 (Tomcat 7 after all is still supported in 2019).  The following, although it says tomcat8, installs tomcat 8.5.

sudo apt install tomcat8

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

For a headless server you can test by installing a non graphical browser such as lynx.  Otherwise test from another machine by replacing localhost with the IP of the server.

Other Dependencies

sudo apt install unzip curl pgpgpg ufw

Generate a key for use in OSCAR

sudo mkdir /usr/share/tomcat8/.gnupg
sudo chown tomcat8:tomcat8 /usr/share/tomcat8/.gnupg
sudo -H -u tomcat8 bash -c 'gpg --gen-key'

To configure OSCAR to use pgpgpg you need to change the oscar.properties file key value to the uid you selected

PGP_KEY: name <email@address>

The PGP_KEY is the ID for the key that you generated

Also update the location of the keyring and configuration

PGP_ENV: GNUPGHOME=/usr/share/tomcat8/.gnupg

 

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

• Tomcat 8 support requires DEB_VERSION to be 89 or higher for installation.
• 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-97~855.deb

 Now simply run the package and follow the instructions

sudo dpkg -i oscar_emr15-97~855.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/tomcat8/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 

Tomcat Troubleshooting

If Tomcat 8.5 runs into a binding conflict with a logging jar, Oscar will not start.  Its no longer necessary and can be removed with

sudo rm /var/lib/tomcat8/webapps/oscar/WEB-INF/lib/slf4j-simple-1.7.6.jar 
sudo service tomcat8 restart

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 either self-signed, or it is a proper certificate but accessed on the local network and not on what you supplied for the FQND (www.example.org) .   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

Principles of layered security require that a firewall be configured on the server even if your box is behind a solid open source router such as pfSense.

Uncomplicated Firewall

The default settings should allow all outgoing connections and deny all incoming

sudo ufw default deny incoming
sudo ufw default allow outgoing

Now set your minimal allowed ports. 

The following are ports that you will need to consider in any firewall on an OSCAR server

• As a minimum users will access OSCAR externally on port 8443, it needs to be open
  
• if you are using SSH to access your sever you need to allow your port (usually 22) *before* you enable the firewall
• OPTIONAL Certbot needs port 80 to renew the server certificate
• OPTIONAL Phpmyadmin uses port 80 to administer MariaDB
  
• OSCAR uses port 3306 locally to access patient data in MariDB, it can be closed to external access
  
• OSCAR uses port 8080 locally to access drugref for the lists of drugs, it can be closed to external access
  

sudo ufw allow 8443
sudo ufw allow 22

ports 3306 and 8080 will be blocked to external access with the default rules but I like to explicitly close them with

sudo ufw close 3306
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 upgrading will occasionally break functionality with a new bug, be prepared to revert by downgrading.  Ensure you have backup in hand (!) and then you can

sudo dpkg -i oscar_emr15-92~851.deb

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.  Delete the existing oscar.war first to be sure that newer java classes can be replaced with the older ones provided in the older deb.

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

then run the older deb over the new one.  If you are using Tomcat 8.5 (as in these instructions) you need to keep to a deb in 88 series or higher.

sudo dpkg -i oscar_emr15-88~844.deb