Search the OSCAR Documentation
< All Topics

Installation of OSCAR 19 on Ubuntu 18.04

Share this
Want a fully-featured EMR setup for the lowest cost guaranteed?
Go here - The only option with NO monthly or per-user user fees.

Preface

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

WARNING:  these instructions have been deprecated in favour of those for installation on Ubuntu 20.04

Ubuntu 18.04 will no longer be supported as of April 2023 and should NOT be used for production past that date. These instructions are here for reference for rebuilding existing installations.

Document Version History

  • v1.0 – initial OSCAR 19 version published to worldemr.org – April 25, 2019
  • v1.1 – expanded PGP instructions to include configuration details – May 16, 2019
  • v1.2 – reverted to Open Java 8 – May 22, 2019
  • v1.3 – added instructions for J9 as an option – January 31, 2020
  • v1.4– extended memory considerations added – December 22, 2020 – January 4, 2021
  • v1.5 – added Note at top – December 17, 2021
  • v1.6 – removed note from Top and moved to troubleshooting as this has been resolved in the current DEBs – Jan 5, 2022
  • v1.7 – added warning that these instructions have been supplanted by those for Ubuntu 20.04 – March 25, 2022
  • v1.8 – added warning about the security issues associated with wkhtmltopdf –Dec 29, 2022

Documentation Copyright © 2012-2022 by Peter Hutten-Czapski MD, with additions from Adrian Starzynski 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 30 minutes to install Ubuntu, 11 minutes to install the infrastructure packages, and a final 15 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.
  2. You are using suitable hardware.  While the OSCAR server may run on recent CPUs with 2GB RAM I consider 3GB a minimum.  I suggest aiming to consumer grade machines with 8GB RAM for 1-3 MD’s increasing to server grade machines with 32GB for 7+ MD’s.  Server grade machines offer component redundancy and improved reliability that is an advantage in any setting, but all systems need contingency plans for hardware failure. The author runs Intel Xeon server with 72GB RAM and hardware RAID as well as a i7 backup server with 16GB RAM for a database that is 8GB (compressed) in size and has 24 users.
  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. When provisioning the VM consider that the base install of Ubuntu and OSCAR will need about 15 GB.
  4. You have installed the 18.04 64 bit LTS version of Ubuntu.  Both desktop and server versions have been tested and are supported to April 2023.  We strongly recommend *full disk encryption*, if you are able to manually provide the password after a power outage or reboot.
  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. )
  7. There are significant disadvantages of trying ANY other version of the software versions specified herein unless you have extensive OSCAR configuration experience.  Better to get it running on spec and only then try something a bit different.

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

Installing The Infrastructure Packages

WE REITERATE Its a noob error to deviate from these instructions in favour of something newer or “easier.” For production use we recommend these exact instructions as the community to support you if you are having problems.  If you are both familiar with OSCAR and are testing or are willing to take chances when you colour outside the lines feel free to deviate from the instructions as you wish (review the version notes at the bottom), and if its substantive deviation (and it works), please submit back your version. 

First ensure that the Universe repository is available (it probably is) and regardless update to ensure that the appropriate packages are available.

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

OPTIONAL components Certbot

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  FQDN (I mean you own your website name eg www.example.com).

Certbot will register your server with Lets Encrypt so that external browser access to the OSCAR will be with a green padlock for a trusted connection.

To install certbot execute the following

sudo apt install certbot

Certbot sets up a temporary standalone webserver that needs to communicate on port 80 to the lets encrypt server to authenticate that you are the owner of the website.  If your server is behind a router/firewalls you will need to open port 80 on your router and forward that port as port 80 on your server.  Those instructions vary by router.  In the following replace FQDN with your the fully qualified domain name that you own (eg www.example.org)

sudo certbot certonly --standalone -d FQDN

Test by checking if there are files as below

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

The OSCAR Deb installer will install the certificate for you when it runs.

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 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.  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:

  • Running without an X11 server.
  • Printing more than one HTML document into a PDF file.
  • Adding a document outline to the PDF file.
  • Adding headers and footers to the PDF file.
  • Generating a table of contents.
  • Adding links in the generated PDF file.
  • Printing using the screen media-type.
  • Disabling the smart shrink feature of webkit.

The only feature that OSCAR has to have in a headless server is the ability to run without  X11.  The ability to disable the smart shrink can solve some output issues. You can get this version from the developer, and then install it and its dependencies with apt. You are on your own to notice download and install newer versions.  Note that versions 12.6 and above disable local file access by default and needs to be run with --enable-local-file-access.

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://worldemr.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.

 
 
If you don’t get a welcome screen then it is likely that Tomcat is not picking up your java, see troubleshooting in the Java section above.
 

Unzip Curl

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. Uncomplicated Fire Wall (ufw) will secure the server.  Apt-get them
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.

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

Version Notes

The above is tested as the default installation that works with the DEB. Certain variations are supported, some of which are mentioned here. Everything else is not tested and will likely require more time than you think to get it to work (usually accomplished by backtracking to the above tested methods)

See the article on software and versions for variations and considerations when using other software as well as duration of open source security patches with end of life dates for various components of the OSCAR stack.

For finishing security touches see the second article in this series

For migration from OSCAR 15 see the section on updates and migrations

Troubleshooting

Note: There are 2 issues with *some* DEBS using the current instructions.

1) Ubuntu 18.04 LTS will install MariaDB 10.1.  The database installation script for SOME DEBs will cause errors on MariaDB 10.1 The simplest solution is to install MariaDB 10.3 instead of 10.1.  This page describes the upgrade procedure: https://mariadb.com/docs/operations/upgrades/upgrade-community-server-cs10-3-ubuntu18/

2) The demo data script (demo.sql) for SOME DEBs will fail due to a conflict with the demographic.pref_name field. Either do not install the demo data or use the latest DEBs where this has been resolved

 

 

Table of Contents