EMERSE Installation Guide

To install EMERSE, someone with sys admin skills is desirable. This person should be able to install and configure software, edit database tables, etc. No actual programmer experience is needed for a default installation and configuration of EMERSE. Knowledge of servers, Java, Linux, and Apache software will be useful skills for this installation.

The initial setup described in this guide can probably be done in a day or less. More time will be required for additional customizations and planning related to localized needs, document extraction and indexing, regulatory approval, etc.

A Linux/Unix based server is suggested for installing the application server and for hosting the indexing services. No specific type of storage is required, but in general the server should be connected to the highest speed storage available. EMERSE performs a lot of disk reads to retrieve the documents, so read performance is important. We have conducted some experiments using SSD storage and have found it to provide nearly a two-fold increase in system performance for EMERSE, most noticeably in the area where all documents are retrieved and highlighted for a pre-defined set of patients.

Storage capacity is dependent on number of documents to be indexed. While no longer our latest statistics, at one point at Michigan Medicine 2.2TB was used to host approximately 166 million documents in both TXT and HTML format on the production server. An additional 4 TB was available for index optimization, as optimization requires about 2x the size of the index. If your documents are heavily formatted (e.g., HTML instead of TXT), storage requirements may be higher.

EMERSE doesn’t place great demand on the Oracle database, so a relatively small server can be used with 10-50 GB of storage allocated for user tablespaces. While no longer up-to-date, at one point at Michigan Medicine we were using 8 GB of database space for production EMERSE with 600+ users and 5 years of data (audit logs, user settings, etc).

The first step in installing EMERSE is to download and install a Java Development Kit (JDK) on the server. Java 11 or higher is required because it was compiled under that version.

Operating Systems often include a Java runtime, and is available on the PATH variable. We will use the java available from the linux distribution’s package manager, and install it like so:

The latter command should print out the java version installed, and confirms that Java is on the path.

EMERSE is packaged as a Java based WAR file that will be deployed to the Tomcat Servlet engine. Tomcat depends on a Java JDK. Tomcat version 9.0.7+ is required. The Tomcat download page lists a number of components available for download. Only the "Core" software is required. See Required Software section.

We’ll navigate to the apache website and click on the "tar.gz" link under the "Core" bullet point. This should download apache from a mirror near you. Then unzip the in the /app directory:

Let’s start tomcat to confirm it’s running:

Open a browser and navigate to http://localhost:8080/. A Tomcat welcome screen should appear.

To stop tomcat, you just need to do:

(Though you don’t need to do that now.)

EMERSE leverages Apache Solr for searching documents. See Required Software section for the specific version to use. The Solr version should have the same major version as specified, and a minimum of the minor version. Otherwise, the sample indexes provided may not be usable, and EMERSE may not function.

Navigate your browser to https://solr.apache.org/downloads.html and download the latest .tgz BINARY release of Solr. We’ll expand it under /app and rename it, just like tomcat:

Let’s start solr to confirm it’s installed correctly:

and then navigate your browser to http://localhost:8983/solr/. You should the solr admin tool dashboard.

A database is needed for EMERSE. For the purposes of getting started, we’ll use the MariaDB database, since it’s often installable using linux package manages.

Database servers are often configured to be automatically started up as a "service" when the computer is booted. Different linux systems do this different ways, but the most common, especially for RedHat systems, is systemd. For Fedora, this looks like:

If you don’t want it started at boot, don’t "enable" the service. It can be started while "disabled."

To confirm it’s running, run the mariadb command, which attempts to connect to the database:

You should either get a command prompt for the database, or a permission error, such as "Access denied for user…​" You should not get an error saying it cannot get to the server, or cannot find a file named mysql.sock or a similar name.

If you are using Microsoft SQL Server as the backend database, we recommend two additional steps to ensure adequate performance.

From here on out, you’ll start installing software developed here at Michigan Medicine. Our software, along with SQL install scripts, and related files are all stored in our private EMERSE project page on GitHub. To access this repository and hence the rest of the installation materials, please contact the EMERSE team and provide us with your GitHub ID.

All installation files are "assets" on release pages of the EMERSE project. Generally, we don’t duplicate all the files needed to install EMERSE on each release, because many files don’t change, and many files that don’t change are extremely large (such as the example index files). For this reason, we only attach the changed files for each release. Thus, if you need a file named, say, emerse.properties you should search from the most recent release to the least recent release for the file with that name, or a very similar name. For instance, if you see emerse.properties on releases 6.1.1, 6.1, and on 6.0, you should use the one from 6.1.1. Similarly, if you are looking for emerse-solr-6.0.jar and you see it on release 6.0 but also see a emerse-solr.jar on release 6.1, you should use the 6.1 version. (We try not to have versions in our file names so that the file name is an exact match across versions.)

While not necessary, it can be helpful to have the system startup every time the server is started or rebooted, rather than entering the startup commands for each component every time. To do this, create a shell script in /app that will contain the commands to launch the two components:

Make the script executable:

This script assumes the database starts up on reboot already. If you chose not to do that when you install the database and what to do that now, it should be a command similar to

but it depends on your linux distribution, or how you installed your database. Alternately, you can add the database start and stop commands to this script.

Now add that startup script to a crontab. To create the file, type:

If you have followed the directions outlined in this document and installed Redhat Linux, it may open up the file using the vi editor. If so, type i for insert, then type one line as follows:

Then, to save the file, type esc [escape] and then :wq and enter to close and save the file. To verify that the crontab is there, type

It should show the line above (beginning with @reboot). At this point, restarting the server should allow all of the required components to startup automatically.

Once an initial implementation is complete, local customization work will need to be done including identifying document sources, proper indexing with metadata in Solr, and other configurations related to document display in EMERSE. These are detailed in other guides, such as the EMERSE Configuration and Optimization Guide and the EMERSE Data Guide. However, a good place to go to next is the EMERSE Setup Guide which will walk you through additional steps in setting up the system with your own data.