Installation of OSCAR 19 on Ubuntu 18.04

JAVA

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

Open JDK is provided by many binaries (look for ones that are Java SE compatible) including those provided by AdoptOpenJDK, Zulu, J9, Corretto, etc and those packaged by many Linux distros including Ubuntu.  OSCAR 19 has been tested in production environments with Ubuntu JDK 8, Eclipse J9 JDK8 and Zulu JDK 8. Pick one of the following.

a) UBUNTU Open JDK 8

The Open JDK 8 packaged by Ubuntu is currently the default recommendation.

sudo apt-get install openjdk-8-jdk

Test if desired (your output will be slightly different):

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

b)J9 Open JDK 8

The Eclipse J9 is suggested if you are having Java errors with the Ubuntu package. Its JVM is completely different than hotspot which may be a performance advantage.  If you add the repository as below it will also get automated updates.

$ 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

Test if desired (your output will be slightly different):

$ java -version
openjdk version "1.8.0_232"
OpenJDK Runtime Environment (build 1.8.0_232-b09)
Eclipse OpenJ9 VM (build openj9-0.17.0, JRE 1.8.0 Linux amd64-64-Bit Compressed References 20191017_442 (JIT enabled, AOT enabled)
OpenJ9   - 77c1cf708
OMR      - 20db4fbc
JCL      - 97b5ec8f383 based on jdk8u232-b09)

Setting the Java for the one you want

You should check and change what /usr/bin/java points at with update-alternatives BEFORE you run the OSCAR DEB

$ 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 three Java configured and Zulu 8 is set as the default.

For a new install the DEB will pick the update-alternatives configured Java 8 at time of installation regardless of brand.  If you change the configured Java after initial installation you must manually change to the correct JDK with the $JAVA_HOME setting in

$ sudo nano /etc/default/tomcat8

For example below we have commented out the Ubuntu open JDK and configured J9

#JAVA_HOME=/usr/lib/jvm/java-8-openjdk-amd64
JAVA_HOME=/usr/lib/jvm/adoptopenjdk-8-openj9-amd64

NOTE: JAVA OPTIONS also in /etc/default/tomcat8 are set by the OSCAR DEB to that what is compatible with most Open JDK’s but you may get better performance by adjusting them from the defaults.  To adjust, you should review the documentation of the package you are using.   J9 in specific has a long history with some interesting garbage collection modes and some package specific  modes detailed at https://www.eclipse.org/openj9/docs/cmdline_migration/

Other Infrastructure Dependencies

wkhtmltopdf

 WARNING: see version notes about security risks and how to mitigate them associated with this component.

OSCAR uses wkhtmltopdf to print PDF content from HTML eforms. 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.  It is not updated frequently.

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

If you don’t like the output or you have a headless server, the wkhtmltopdf maintained by the developers has a patched QT and more features.  Currently the list of additional features include:

For OSCAR to pick up this binary either change the OSCAR property file or make a link

sudo ln -s /usr/local/bin/wkhtmltopdf /usr/bin/wkhtmltopdf

Test it to check the resultant pdf to see that it has the following output and displays correctly.

$ wkhtmltopdf -s Letter -T 10mm -L 8mm -R 8mm --print-media-type --disable-smart-shrinking --enable-local-file-access http://oscargalaxy.org test.pdf
Loading pages (1/6)
Counting pages (2/6)                                               
Resolving links (4/6)                                                       
Loading headers and footers (5/6)                                           
Printing pages (6/6)
Done

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)

Feel free to use numbers and letters in your password.  If you proceed with the complication of using symbols “#,!, &,*, (, ), / , \ and $” in this password (e.g. pass&word), be sure to escape them when providing them to scripts below where the instructions supply ******  that require it (e.g. pass\&word).

$ 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 although this is technically possible with 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.

Unzip Curl

sudo apt install unzip curl pgpgpg ufw

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

• The progression of any release is alpha, beta, release candidate, and then general release which reflects the amount of formal and informal testing that the build has undergone
• We recommend the latest OSCAR 19 general release for production
• Note that stability is not necessarily improved by a higher build number.
• 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.

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

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

You can see a quick list of the latest few debs here.

wget http://sourceforge.net/projects/oscarmcmaster/files/Oscar\ Debian\+Ubuntu\ deb\ Package/oscar_emr19-35~1182.deb

Now simply run the package and follow the instructions

sudo dpkg -i oscar_emr19-35~1182.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/Oscar19install.log

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

 

Start by providing the MySQL/MariaDB password you assigned.  OSCAR will use it to set up a modernized  version of the oscar_15 database for OSCAR 19.

 

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, escaping any symbols (if any) that you used in the 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.

The terminal will provide feedback as OSCAR is assembled and configured.

Allow for a good quarter hour 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, Edge etc) will work, for production use we strongly recommend FireFox ESR version, for stability, for tested OSCAR features and a large number of grease monkey addons that you can get on these pages.  It also is open source and doesn’t sell your data.

Whatever browser you choose 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 FQDN (www.something.org) .   As it is your installation you can safely click on “Advanced” and set an exception and proceed to your OSCAR server.

 

Sometimes you get an Apache Tomcat error page indicating that the resource (oscar) is not available.  This usually will occur if you have inadequate memory allocated (see above for minimum and suggested provisioning).

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 standard instructions for hardening for Tomcat 8 provided by Apache and others on the web.

The initial login parameters for OSCAR are as follows:

User Name: oscardoc
Password: mac2002
PIN (Second Level Passcode): 1117

When you login, you will be presented with a one time password reset for security purposes.
8 characters upper and lower case numbers and symbols are required in a password with default oscar.properties settings

 

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

For finishing security touches see the second article in this series