(Current) OSCAR EMR 19 Installation (Draft)

1.1 Manual Installation of OSCAR Components

1.1.1 Prerequisites

• For new installations, Ubuntu 18.04.x LTS (the Long Term Support version) or later is recommended. Whole disk encryption is recommended. For existing installs, it is acceptable to use other supported LTS versions of Ubuntu.

• The host computer should be dedicated to OSCAR and have access restricted to trusted users.

• Always use secure passwords/encryption keys/passphrases that contain at least 8 characters including a mixture of at least 3 of the following: upper case letters, lower case letters, digits and symbols. This also applies to keystore passwords used for Tomcat SSL/TLS configuration, for instance. Also, never leave any default passwords (on gateway routers, etc.) unchanged that may impact the security of your Oscar installation.

1.1.2 Update the System

Install system updates and restart server.

sudo apt update

sudo apt upgrade

shutdown –r now

1.1.3 Installing the Infrastructure Packages

1.1.3.1 Java 8

OSCAR is written in the Java programming language. It is known to work with Open JDK 8 which is available as a Ubuntu package.

sudo apt install openjdk-8-jdk

1.1.3.2 Tomcat 8.5

To support OSCAR’s web based user interface, the system leverages the extensive resources of the Apache Tomcat web application framework. Install Tomcat using:

sudo apt install tomcat8

At this point, tomcat8 may fail to start because the environment variable JAVA_HOME is undefined. Also, to run Oscar successfully, the tomcat8 configuration must be modified. Tomcat will need to use more memory then the default allocation allows. Open the Tomcat settings file (/usr/default/tomcat8) using your text editor. You can use whichever editor you choose. In these instructions, we will use nano:

sudo nano /etc/default/tomcat8

Add the following two lines to the end of the file.

JAVA_HOME="/usr/lib/jvm/java-8-openjdk-amd64"

JAVA_OPTS="-Djava.awt.headless=true -Xmx1024m -Xms256m -XX:MaxPermSize=512m -XX:+UseConcMarkSweepGC -XX:+CMSIncrementalMode -server"

Save the file and exit nano¹.

Optionally, include within JAVA_OPTS above the parameter “‑Djava.security.egd=file:/dev/./urandom” to speed startup and to ensure that Tomcat doesn't block. For an explanation of how this option works, see http://www.thezonemanager.com/2015/07/whats-so-special-about-devurandom.html. Note: Be very careful with Tomcat configuration file changes. Test Tomcat by using Stop and Start to ensure changes do not cause Tomcat starting issues.

If the installation of tomcat8 failed to complete because JAVA_HOME was undefined, complete the installation process with:

sudo apt upgrade

Respond yes when asked whether you want to use the previous configuration. That configuration is in /etc/default/tomcat8 which you have just edited to include JAVA_HOME.

It should now be possible to restart Tomcat (without errors) using this command:

sudo service tomcat8 restart

A few other environment variables are useful when working with OSCAR. One way to make these environment variables available system-wide is by adding them to /etc/profile.

sudo nano /etc/profile

If you are configuring OSCAR on a freshly installed Ubuntu server, then you should be safe to add these lines to the end of the file.

JAVA_HOME="/usr/lib/jvm/java-8-openjdk-amd64"

CATALINA_HOME="/usr/share/tomcat8"

CATALINA_BASE="/var/lib/tomcat8"

export JAVA_HOME CATALINA_HOME CATALINA_BASE

Save and exit nano. To load the new environment variables into your existing terminal, run the following command. Please note that the sudo command should not be used here. (Warning: An error in /etc/profile could prevent login. Be very careful when editing this file. After /etc/profile has been edited and before logging out, it is good practice to confirm that login is still possible.)

source /etc/profile

Tomcat should now be security hardened to use SSL connections. We will illustrate the process using a self-signed certificate but a production system should use certificates issued by a trusted certificate authority. An SSL certificate for tomcat can be generated using:

sudo $JAVA_HOME/bin/keytool -genkey -alias tomcat -validity 3650 -keyalg RSA -keystore /etc/tomcat8/.keystore -keypass changeit -storepass changeit

Note that “changeit” must be replaced with a strong password. Then the following code needs to be added to $CATALINA_BASE/conf/server.xml where the password used for keystorePass has to be the strong password used to create the ssl certificate:

<Connector port="8443"

maxHttpHeaderSize="8192"

protocol="org.apache.coyote.http11.Http11Protocol"

SSLEnabled="true"

maxThreads="150"

minSpareThreads="25"

maxSpareThreads="75"

acceptCount="100"

scheme="https"

secure="true"

enableLookups="false"

disableUploadTimeout="true"

clientAuth="false"

keystoreFile="/etc/tomcat8/.keystore"

keystorePass="changeit"

sslProtocol="TLS"

ciphers="TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256, TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384, TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_RSA_WITH_RC4_128_SHA, TLS_RSA_WITH_AES_128_CBC_SHA256,TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA256, TLS_RSA_WITH_AES_256_CBC_SHA,SSL_RSA_WITH_RC4_128_SHA" />

You should also modify the Connector on port 8080 so that it only accepts connections from localhost. Drugref2, which we install later, runs in the same Tomcat instance as OSCAR and communicates with OSCAR via port 8080. However, this modification prevents external access to OSCAR. The Connector configuration will look like this:

<Connector port="8080" enableLookups="false" protocol="HTTP/1.1"

address="127.0.0.1"

connectionTimeout="20000"

URIEncoding="UTF-8"

redirectPort="8443" />

By default $CATALINA_BASE/conf/server.xml is world readable. Since it now contains the keystore password, change permissions to prevent it being read by non-privileged users:

sudo chmod 640 server.xml

Now restart tomcat8 and verify that it is running on port 8443. If you are using a self-signed certificate, curl will complain about the certificate. You can use ‘curl –insecure’ for testing.

sudo service tomcat8 restart

curl --insecure https://localhost:8443/

1.1.3.3 MariaDB 10.0.x

Your specific CMS data, profiles, and information will all be stored in the MariaDB database. (Ubuntu 18.04.x LTS no longer supports MySQL 5.5. MariaDB 10.0.x is an open-source binary-compatible fork of MySQL that is supported by Ubuntu 18.04.x LTS. OSCAR 19 can use MariaDB 10 without code changes.) Read the instructions presented by the database installation script. Accept the suggested defaults. There will be no current password if this is a new installation.

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

sudo mysql_secure_installation

The installation sequence will ask you to set a root password. Enter it. You will be prompted to enter the password again to verify.

By default, Linux root credentials are required to log into the MariaDB server. OSCAR will need to login without Linux root credentials. Bypass the plugin requiring root credentials:

$ sudo mysql -uroot –p

MariaDB [(none)]> use mysql;

MariaDB [mysql]> update user set plugin='' where User='root';

MariaDB [mysql]> flush privileges;

MariaDB [mysql]> quit

$ mysql –uroot –p

MariaDB [(none)]> quit

By default, new databases created in MariaDB will use the UTF8MB4 character set whereas new databases created in MySQL 5.5 use latin1, if the character set is left unspecified.

1.1.3.4 wkhtmltopdf

The package wkhtmltopdf is used to print some pdf content. It can be installed using:

sudo apt install wkhtmltopdf

sudo apt install xvfb

echo -e '#!/bin/bash\nxvfb-run -a --server-args="-screen 0, 1024x768x24" /usr/bin/wkhtmltopdf -q $*' > /tmp/wkhtmltopdf.sh

chmod a+x /tmp/wkhtmltopdf.sh

sudo mv /tmp/wkhtmltopdf.sh /usr/bin/

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

After refreshing your path, you can test wkhtmltopdf with:

wkhtmltopdf -s Letter -T 10mm -L 8mm -R 8mm http://oscarmanual.org test.pdf

1.1.4 Getting the OSCAR Code (WAR File)

We will now download the binary WAR file from Jenkins and move it to $CATALINA_BASE (which you set to /var/lib/tomcat8 earlier in this manual).

Please get the latest recommended Oscar release and build number from Oscar EMR. The most recent OSCAR software builds are available at http://jenkins.oscar-emr.com:8080/job/oscar-stable/. Older builds are archived in Dropbox and can be found following links provided at https://oscaremr.atlassian.net/wiki/spaces/OS/pages/86938572/OSCAR+Builds.

The most recent successfully built (but likely not QA tested) WAR file is at:

http://jenkins.oscar-emr.com:8080/job/oscar-stable/lastSuccessfulBuild/artifact/target/

(The database matching this war is at http://jenkins.oscar-emr.com:8080/job/oscar-stable/lastSuccessfulBuild/artifact/database/. Note that both war and database can be downloaded in a single zip file from http://jenkins.oscar-emr.com:8080/job/oscar-stable/lastSuccessfulBuild/artifact/ )

Click the “oscar-14.0.0-SNAPSHOT.war” link in your browser to download the WAR file. By default Firefox will download the files to the “Downloads” directory under your Home directory. You can change the file name but always keep the “.war” extension. In this example, you must change the file name to “oscar.war” for the rest of the instructions to work. From the Downloads directory

cd ~/Downloads

mv oscar-14.0.0-SNAPSHOT.war oscar.war

You now need to copy the WAR file to $CATALINA_BASE/webapps/ on the Oscar server. You may need to reset the access rights of the file using the “chmod” command; this is to ensure there is no access right issue. Run the following commands, assuming you are in a directory to where the war file has been copied on your server:

sudo cp oscar.war $CATALINA_BASE/webapps/

sudo chown tomcat8:tomcat8 $CATALINA_BASE/webapps/oscar.war

sudo chmod 644 $CATALINA_BASE/webapps/oscar.war

There will be disk activity as Tomcat unpacks the war and it will take time. You should see an oscar/ directory created in your $CATALINA_BASE/webapps/ directory.

Now you have the OSCAR code in your computer, but code needs data to work on. If you examine the tomcat8 log in /var/log/tomcat8/catalina.out, you will see that OSCAR will have failed to locate the database. In the next section you will create and set up the OSCAR database on your computer.

1.1.5 Create the OSCAR Database

First, go to Jenkins or Dropbox to download the latest database scripts related to the build. As noted above, the database will be archived together with the war downloaded above. Pick the database matching the release and build number of the build that you plan to install.

Copy the zip file to the server home directory. Unzip and make the scripts executable:

unzip database.zip

cd database

chmod 755 mysql/*.sh

OSCAR includes scripts to create and populate the MariaDB database. (The database name used here is oscar but that can be changed). Current versions of stable will specify the UTF8 character set while creating the OSCAR database. That is necessary because some of OSCAR’s indexes become too large using MariaDB’s default UTF8BM4 character set.

OSCAR users that are from neither Ontario nor BC can run either of the above commands (you must run one of them; we use the Ontario one in this example). If you ever need to reinitialize the database, you can use the same script.

Note that while the database creation script runs, any user with shell access to the host can see the password entered above using the 'ps' command. Also, running this command leaves the password in the bash history file of the account used to create the database. To prevent any possibility that this entry in the history file can be viewed by a non-trusted user, delete it from the history using 'history -d nnnn' with nnnn replaced by the number displayed before the createdatabase_xx.sh … entry in the history listing.

If you have already setup an oscar database before and need to update it, you can find all the update scripts in the mysql/updates/ subdirectory.

1.1.6 Setting Up OSCAR Properties

You will need an oscar.properties file. Prior to tomcat8, properties files were kept in the $CATALINA_HOME directory. Tomcat8 expects to find them in your $CATALINA_BASE directory. We will continue to keep the properties file in $CATALINA_HOME but add a symbolic link to the file from $CATALINA_BASE. (Note that if you renamed the Oscar war file to something different than oscar.war then the properties file will also be named differently. For instance, if the war is named oscar19.war then the properties file should be named oscar19.properties.) The oscar.properties file must be readable by tomcat8. It should not be world-readable as it will contain the OSCAR database password.

You can find a sample of the properties file at:

$CATALINA_BASE/webapps/oscar/WEB-INF/classes/oscar_mcmaster.properties

To copy the sample properties files to $CATALINA_HOME directory:

sudo cp $CATALINA_BASE/webapps/oscar/WEB-INF/\ classes/oscar_mcmaster.properties $CATALINA_HOME/oscar.properties

sudo chown tomcat8:tomcat8 $CATALINA_HOME/oscar.properties

sudo chmod 640 $CATALINA_HOME/oscar.properties

sudo ln -s $CATALINA_HOME/oscar.properties \ $CATALINA_BASE/oscar.properties

Once you copy the file to the $CATALINA_HOME directory, you can edit the file with any editor you want. We’re still using nano:

sudo nano $CATALINA_HOME/oscar.properties

Uncomment and set the database name. If you database name is different from oscar, modify this line so that it matches your database name.

db_name = oscar?zeroDateTimeBehavior=round&useOldAliasMetadataBehavior=true&jdbcCompliantTruncation=false

Change the db_password to match the MariaDB database password that you set earlier

Set the default prefix for phone numbers in your area to save the reception keystrokes (TIP this is not limited to an area code e.g. "905-6" might be efficient)

phoneprefix=905-

Set the default billing center; note the bill center codes are listed in the properties file

billcenter=D

BC users will probably want to adjust the following to match their environment

visitlocation = P1|PEMBERTON

dataCenterId = 00000

msp_error_codes = # supply the file location of msp error codes

billregion=BC

NEW_BC_TELEPLAN=yes

CDM_ALERTS=250,428,4280

COUNSELING_CODES=18220,18120,17220,17120,16220,16120,13220,12220,12120,00120

It is recommended that the following configuration parameters be added to the oscar.properties file if they are not already there. HL7TEXT_LABS=yes allows you to display labs and SINGLE_PAGE_CHART=true enables access to the new UI from the appointment menu. To allow import and export of patient charts, the TMP_DIR directory should be set to a secure temporary document directory (the example below uses /usr/share/oscar-emr/tmp) owned by tomcat8, belonging to the tomcat8 group, with rights to the directory restricted (chown tomcat8:tomcat8 and chmod 750 on directory).

HL7TEXT_LABS=yes

SINGLE_PAGE_CHART=true

TMP_DIR=/usr/share/oscar-emr/tmp

It is not necessary to define the ModuleNames parameter unless you are using a specific module outside of standard OSCAR functionality. Only the last ModuleNames parameter in the Oscar properties file is used so if you need to use more than one module, they must be listed together separated by commas.

ModuleNames=FAX,Jobs,BORN

Save oscar.properties file and exit your editor. You are almost done!

1.1.7 Importing Drugref 2

The drug database is actually a small separate server -- not part of OSCAR proper. It gets its data from Health Canada’s drug database, and you can update your Drugref database whenever you want from within OSCAR. But in order to use that data, you’ll first need to create a local “Drugref” database on your server and import data into it.

You can get the Drugref WAR file from Jenkins:

http://jenkins.oscar-emr.com:8080/job/drugref2/lastSuccessfulBuild/

First, move the Drugref WAR file from the download directory to $CATALINA_BASE and edit the drugref2.properties file to let Tomcat have access to the Drugref database:

mv drugref2-1.0-SNAPSHOT.war drugref2.war

sudo mv drugref2.war $CATALINA_BASE/webapps

sudo chown tomcat8:tomcat8 $CATALINA_BASE/webapps/drugref2.war

sudo chmod 644 $CATALINA_BASE/webapps/drugref2.war

Launch your text editor to create drugref2.properties:

sudo nano $CATALINA_HOME/drugref2.properties

Enter the following lines into drugref2.properties. Replace ****** with the MariaDB password you set earlier.

db_user=root

db_password=******

db_url=jdbc:mysql://127.0.0.1:3306/drugref

db_driver=com.mysql.jdbc.Driver

Make sure that the drugref2.properties file is owned by tomcat8, belongs to the tomcat8 group and is not world readable as it contains the root password for the database (chown 640).

In your oscar.properties, add the following line (or change it if the property already exists):

drugref_url = http://localhost:8080/drugref2/DrugrefService

Note: If you decide to put your Drugref service in a separate server, change localhost:8080 to your corresponding host address : port number.

Create a new database with UTF8 character set for Drugref. You will be prompted for the root MariaDB password you set earlier:

mysql -uroot -p -e "CREATE DATABASE drugref CHARACTER SET UTF8 COLLATE UTF8_GENERAL_CI;"

Restart tomcat so OSCAR and Drugref2 reload their properties.

ln -s $CATALINA_HOME/drugref2.properties \ $CATALINA_BASE/drugref2.properties

sudo service tomcat8 restart

Your Drugref database is still empty. To populate it with the latest data, run the following command on the server:

$ curl http://localhost:8080/drugref2/Update.jsp

The data loading process does not provide any screen to show progress but is simply kept in a refresh state. The update takes less than an hour to complete. If you want to monitor progress, you can issue this command in a separate terminal session:

sudo tail –f /var/log/tomcat8/catalina.out

If you have a desktop environment installed on the server and have loaded http://localhost:8080/drugref2/Update.jsp using a web browser, you can leave the browser open and wait for the complete page to show, or you can close the browser – the server will continue updating the Drugref database until finished. When the update is finished, a screen similar to the one below will be shown on the browser page.

The Drugref database should be updated periodically. It can be updated from within OSCAR by the administrative user clicking on the Administration tab, selecting Integration and then “Update Drugref”, or it can be updated in the same way it was initialized. Before updating an existing Drugref database, it is recommended that that existing Drugref database be backed up so that it can be restored should the attempt to update Drugref fail. (While updating, the existing Drugref database table content is dropped. Should the update fail, the Drugref database will be empty or incomplete.)

1.1.8 Finalizing the Installation

Tomcat needs to be restarted to make the configuration changes take effect.

sudo service tomcat8 restart

(When restarting tomcat8, you may wish to monitor /var/log/tomcat8/catalina.out for error messages during server startup.) Assuming that tomcat8 starts up Oscar successfully, the installation process is done. You can open your browser (we use Firefox) and log into your OSCAR EMR. Remember, since we are using SSL/SSH for secure access to all OSCAR production installations, OSCAR will be running on port 8443 rather than 8080 if you have followed the previous instructions.

1.2 Installation of OSCAR from DEB Files

For users in Ontario that prefer a more integrated installation without managing the different components in OSCAR, installation from DEB packages contributed by community members is possible. The OSCAR 19 DEB files are available at http://sourceforge.net/projects/oscarmcmaster/files/Oscar%20Debian%2BUbuntu%20deb%20Package/

The installation instructions for the community supported OSCAR19 debian package are located at http://oscarmanual.org/15/developers/installation/reference

1.3 Installation of an OSCAR Patch

To deploy a newer WAR file (OSCAR EMR released patch) on an existing system one should follow any directions that come with the patch. The following is a general set of steps to update a deployed OSCAR application patch.

Any OSCAR patch should be first deployed in a test environment to identify the impact on the clinic being upgraded. Each practice has a unique set of data and in many situations the patch could impact the existing clinic workflow or functionality. Upgrading in a development environment with the latest data from production allows the end users to verify, accept and sign-off the change(s) before implementing the patch in production.

Once users approved the patch upgrade and before deployment of the patch to production, it is a mandatory requirement to back up existing database configuration files and folders in the production system first.

Steps for updating the WAR file.

sudo service tomcat8 stop (stop tomcat)

sudo rm $CATALINA_BASE/webapps/oscar.war

sudo rm -rf $CATALINA_BASE/webapps/oscar

sudo rm -rf $CATALINA_BASE/work/Catalina/localhost/oscar

sudo cp <war file> $CATALINA_BASE/webapps/oscar.war

sudo chown tomcat8:tomcat8 $CATALINA_BASE/webapps/oscar.war

sudo chmod 644 $CATALINA_BASE/webapps/oscar.war

sudo service tomcat8 start

Step for applying a DB patch file. You will be prompted for the MariaDB password associated with <username>. <username> is the MariaDB root account if the previous steps were followed.

mysql -u <username> -p <db_name> < /path/to/file.sql