EMERSE Installation Guide

Confirm installation of java by typing into Terminal:

If there are multiple versions of Java installed, and the newly installed version is not set as the default, then confirm the specific installation using:

For example:

You should see a message that says something like:

Since Oracle will be using port 8080, change the Tomcat port from its default (8080) to 8090. Go to the tomcat/conf folder, and edit the server.xml file. to change 8080 to 8090. The server.xml file should be located here:

To edit the file:

The part that needs to be changed should look something like:

To start the server use:

To stop the server use:

For this installation guide it would be:

Point a browser to http://hostname:8090/, or if locally installed point it to http://localhost:8090/. A Tomcat welcome screen should appear.

To start the server use:

To stop the server use:

Using a browser, navigate to http://hostname:8983/solr (such as http://localhost:8983) to confirm Solr installation.

Startup:

or

Shutdown:

or

The default port for the ActiveMQ GUI is 8161. Confirm it is up and running by pointing a web browser to http://hostname:8161/admin (for example, http://localhost:8161/admin). The default username/password is admin/admin.

EMERSE comes with an embedded version of ActiveMQ that is off by default. We do not recommend that you use the embedded version, since it was there primarily to ease some of the internal development. Instead, use a separate installation as described above. If you did want to turn the embedded version on for some reason, that can be done through the Spring Profiles. Example:

Point your browser to:

or

Ignore this section if you do not encounter an error related to installing Oracle-XE

If you encounter an error installing Oracle-XE due to a lack of swap space (see warning, above), you can follow these Redhat Linux directions to increase the swap space on your machine, focusing specifically on the section called"Creating a Swap File". Those directions are briefly summarized below.

In Terminal in the type the following commands:

The additional swap memory should now be available. You can confirm this by typing in the Terminal:

We provide 4 indexes with the default distribution. Three of the indexes are populated with sample data to help with testing the initial setup and configuration, and the fourth is an index containing a list of words used for spell-checking, described below.

The four indexes are:

Two of the indexes (patient and patient-slave) store data about the patients (not real patients in the files that we distribute), and are meant to be populated from the PATIENT table within the Oracle database. These indexes are required by EMERSE and the overall structure/definition of them should not be changed even for your own localized installation. The patient demographic data stored within them will automatically be replaced from the database tables when EMERSE is running. The two patient indexes are used to rapidly summarize details used for graphing the demographics.

A third index is called documents and holds PubMed abstracts (containing no protected health information) as placeholders for sample documents. For your production system you can optionally rename this to something that is more suitable (you would then have to update the name in the Oracle table called SOLR_INDEX, described in the Data Guide). Additionally, other aspects of the configuration for this document index will have to be changed from the included example to match your local institutional needs (e.g., the metadata types included for each document).

The fourth index is called dictionary which holds words that are used by EMERSE for spell checking of terms entered by users. This dictionary index is recommended but is not required. Additionally, no changes should need to be made to this dictionary and it can be used as-is. It is also worth pointing out that the dictionary is in an older Lucene format and not the newer Solr format. This should have no practical implications for use, except that it won’t show up in the standard Solr user interface even though the EMERSE application itself can access it.

Once the four indexes have been downloaded, move them to the default directory within Solr: /app/solor-7.3.1/server/solr/

Change to the /app/solr-7.3.1/server/solr/ directory and unzip the four files:

Also move the solr.xml file to where the indexes are. There may already be one there form the initial Solr installation, so the original one can be removed or just renamed if you want to keep it around.

Provided with the EMERSE distribution are a set of files, each containing SQL statements, that create all needed database objects and sample data that will allow the EMERSE application to startup with a default set of database objects, and sample data in the patients, research studies, synonyms and tables. These scripts should be run as the user and schema setup for the EMERSE application (this will be set by each implementing site), and not a system or sysdba user. We recommend a schema named emerse. The account doesn’t require a DBA role but needs to be able to create database objects such as tables, indexes, sequences and views.

To set up the user/schema for EMERSE, do the following.

Launch SQL Developer.

In SQL Developer click on the green plus-sign icon to make a New Connection…​ or go to File → New…​ Database Connection.

Give any name to the Connection name, such as Administrator Account. The username will be system and the password will be the same password used when initially setting up Oracle. For the directions in the guide, the password demouser was used. Press Test to test the connection (it should say Status: Success if it worked). Save the Connection, and then press Connect.

Now create the actual EMERSE application user for Oracle (this is for the EMERSE application, not a user of EMERSE). In the Query Builder window enter:

And then click on the Run Script icon.

Create another connection: File → New…​ Database Connection.

The connection name can be anything, such as EMERSE connection. For the username and password enter the information used to create the account based on the sql above. In this case, username is emerse and password is demouser.

Test the connection by pressing Test, and you should see Status: Success. Check the box to Save Password and then press the Save button to save this connection. Then press Connect.

At this point you should be ready to run the SQL script that sets up the database for EMERSE and loads in sample data (but not the notes since the notes do not get loaded into the database).

Unzip the file, if necessary (the actual filename may differ between versions):

Execute the file in a SQL tool. For example, to run the script in SQL Developer go to File - > Open…​ and then select the SQL file. After loading the file it should open in a Worksheet tab. Then click on the Run Script icon and wait for the script to finish running. When running the Script it may show a prompt for Select Connection, in which case choose EMERSE connection and then press OK.

EMERSE is configured by primarily one file, emerse.properties. This file tells EMERSE how to connect to Oracle, ActiveMQ, Solr, and LDAP (if using), where the lucene index files are, and additional internal configuration or presentation information such as contact email.

After downloading, move the properties to the home directory of the emerse user using the following commands:

You will need to make some changes to the emerse.properties file to reflect your installation properties such as the URL of the Oracle database if it is running on a separate server. Information on configuring EMERSE application properties is located in the Configuration Guide. If you have followed our directions for the example setup/installation you likely will not need to change any database connection information.

If you cannot store the emerse.properties file in your home directory, you must tell EMERSE where it by setting the system property emerse.properties.filepath. You can do that by creating the file setenv.sh in the bin directory of your tomcat installation.modifying the tomcat server JVM settings. (Use setenv.bat if on windows.)

The next step in getting EMERSE up and running after initial installation of the application server and configuration of the database with default settings is to deploy the EMERSE WAR file.

After downloading, deploy the file. First, rename the supplied war file to emerse.war, then copy the war file to the webapps directory of the Tomcat server. This can be done in one step:

If Tomcat cat is not running, start it:

If Tomcat is using default settings, the WAR file will be exploded into a number of files in a directory called emerse. This directory includes all the files needed to run the application.

First, it would be a good idea to make sure all of the components (Tomcat, Solr, Active MQ) are restarted. Oracle should have been setup to start when the system started up so likely does not need to be launched separately.

To stop the main components:

To re-start the main components:

At this point EMERSE should come up, using the URL:

For example:

If the EMERSE application does not come up, the best place to troubleshoot any issues are in log files inside the Tomcat installation:

After all the required software is installed, one can verify the component wiring by running a diagnosis checklist through the EMERSE app. The check list page can be viewed using the URL:

For example,

The following components are verified on a high level:

The Diagnostics page can also show some errors extracted from the logs. However, if the hardened profile is active, the diagnostics page will not be able to show these error messages and it will be necessary to view it in the protected Admin page instead. This Admin page is described in the Administrator Guide.

To test the installation a bit futher, login and try a search:

At this point, if everything worked, it’s is a very good indication that EMERSE is running well.