Installation

Overview

This document describes how to install and configure Eureka! Clinical Analytics version 1.9 on your own hardware.

Prerequisites

  • You have installed Java Development Kit 1.7 (see the Java developer homepage).
  • You have installed Apache Tomcat (version 7 recommended, see the Tomcat homepage).
  • You have installed Oracle 11g (even the free Oracle XE will do for small installations, see the Oracle XE homepage) and have an account with SYSTEM privileges. This is necessary in order to create users/schemas, and grant appropriate privileges to the created users/schemas.
  • You have installed MySQL version 5 or greater (see the MySQL homepage).
  • You have installed JBoss Application Server version 4.2.2 (required for i2b2, see the JBoss homepage).
  • You have downloaded i2b2 version 1.7 (see the i2b2 homepage). You need the Core Source Code Server download.
  • (Optional) You have installed Apache HTTPD (recommended for performance, see the Apache homepage).

Installing Eureka!

Distribution contents

Unpack the Eureka! binary distribution. The lib directory contains four warfiles that you will install in a servlet container (version_number is the version of Eureka! that you downloaded):

  • eureka-webapp-<version_number>.war (the web application itself)
  • eureka-services-<version_number>.war (the services layer of Eureka!)
  • eureka-protempa-etl-<version_number>.war (the backend data processing layer)
  • cas-server-<version_number>.war (the central authentication server)

Also in the same directory, there will be twelve jarfiles that you will need to install into your container’s lib directory:

  • cas-client-core-3.2.1.jar (CAS authentication framework)
  • cas-client-integration-tomcat-common-3.2.1.jar (common CAS functionality)
  • cas-client-integration-tomcat-v7-3.2.1.jar (CAS integration with the Tomcat app server)
  • commons-codec-1.4.jar (needed for CAS integration)
  • commons-logging-1.1.jar (needed for CAS integration)
  • h2-1.3.171.jar (needed for Protempa in-memory database)
  • log4j-1.2.17.jar (needed for logging from CAS)
  • mail-1.4.jar (support for sending emails to users)
  • mysql-connector-java-5.1.19.jar (MySQL database driver needed for Protege)
  • ojdbc6-11.2.0.3.jar (Oracle database driver)
  • opensaml-1.1.jar (SAML authentication token support for CAS)
  • xmlsec-1.3.0.jar (XML security token format needed for SAML support in CAS)

As a part of the distribution, there is also a directory named bioportal. This directory contains files relating to the set up BioPortal as a knowledge source for Eureka!

Finally, there is an etc directory containing three files, AIW.pprj, aiw.sql and jaas.config.

Eureka! configuration directory

Eureka! requires a configuration directory to be maintained on your filesystem. It will be /etc/eureka on Unix/Linux/MacOSX, and C:\Program Files\Eureka on Windows. The user running Eureka! must have read-write access to this directory. This directory will be referred to as $EUREKA_CONFIG in the remainder of the document.

Set up ontology access

Eureka! uses the Protege ontology editor for storing and accessing its built-in derived data elements.

To setup the ontology, first load the provided aiw.sql file into a MySQL database. To do this, perform the following steps:

First, create a database named protege_3_4_7. Login as root to your database via the mysql command line application, and execute the command create database protege_3_4_7;.

Second, create a user named protegeuser and grant it all privileges for the above database with the following commands:

CREATE USER 'protegeuser'@'%' IDENTIFIED BY PASSWORD 'password';
GRANT ALL ON protege_3_4_7.* TO 'protegeuser'@'%';
FLUSH PRIVILEGES;

Finally, execute the following command from the command line from the etc directory to load the database contents:

mysql protege_3_4_7 -u protegeuser -p < aiw.sql

Enter protegeuser’s password when prompted.

In a production setting, once you have populated the database, you will want to dial back protegeuser’s permissions appropriately.

Finally, create a directory inside of the Eureka! configuration directory, ontologies, and copy the AIW.pprj file into it. Open the file with a text editor, and make the following changes:

  • On the line (string_value "jdbc:mysql://localhost:3306/protege_3_4_7")), change localhost:3306 to the hostname and port number of your MySQL database, if needed.
  • On the line (name "password"), change password to protegeuser’s password.

Set up database users for Eureka!

Create Eureka! users

Create two users in the database, one for the Eureka! services layer, and one for the Eureka! ETL backend. The following SQL code snippet can be used to create these users. Be sure to change PASSWORD to secure passwords. These passwords will be used in later steps to configure Eureka!.

create user eurekaservice identified by "PASSWORD"
    default tablespace users quota 1000M on users temporary tablespace
    temp;
create user eurekabackend identified by "PASSWORD" default tablespace
    users quota 1000M on users temporary tablespace temp;
Assign proper privileges to the Eureka! users

Assign proper privileges to the users to allow the application to connect and perform the normal insert, delete, and other operations on the data. The following SQL code snippet will do this:

grant create session to eurekaservice;
grant create table to eurekaservice;
grant create view to eurekaservice;
grant create any index to eurekaservice;
grant create public synonym to eurekaservice;
grant drop public synonym to eurekaservice;
grant create sequence to eurekaservice;
grant create procedure to eurekaservice;
grant create any type to eurekaservice;
grant alter any type to eurekaservice;
grant drop any type to eurekaservice;
grant execute any type to eurekaservice;
grant under any type to eurekaservice;
grant create any trigger to eurekaservice;
grant alter any trigger to eurekaservice;
grant drop any trigger to eurekaservice;
grant create session to eurekabackend;
grant create table to eurekabackend;
grant create view to eurekabackend;
grant create any index to eurekabackend;
grant create public synonym to eurekabackend;
grant drop public synonym to eurekabackend;
grant create sequence to eurekabackend;
grant create procedure to eurekabackend;
grant create any type to eurekabackend;
grant alter any type to eurekabackend;
grant drop any type to eurekabackend;
grant execute any type to eurekabackend;
grant under any type to eurekabackend;
grant create any trigger to eurekabackend;
grant alter any trigger to eurekabackend;
grant drop any trigger to eurekabackend;
Create services and backend schemas

We use a third-party database migration tool, Liquibase, for creating and updating these database schema. You may use it to create these schemas for the first time, automatically update your schema for a new release, or print out the SQL that would be executed for a database administrator to inspect or apply manually.

To use Liquibase, enter the liquibase-2 directory in the Eureka binary distribution at the command prompt. Edit the liquibase-services.properties and liquibase-backend.properties files with database connection information for your services and backend schemas, respectively. Invoke Liquibase with the following syntax:

(Linux and UNIX)

./liquibase --defaultsFile=liquibase-services.properties <command>
or
./liquibase --defaultsFile=liquibase-backend.properties <command>

The update command will create the schema and update it from a previous release.

Type ./liquibase to see a list of commands. Documentation is available at the Liquibase website.

Prepare to use BioPortal

If you choose to use BioPortal as a knowledge source in your Eureka! installation, you will first need to obtain an API key from BioPortal. Once the key has been obtained, the bioportal/bin/aiw-bioportal-update script from the distribution can be used to create an H2 database that will be used by Eureka! For a full list of arguments for the script, please run the script without any arguments, which will produce a usage message. For configuring Eureka! to use the H2 database produced by the script, please see the Configure the context.xml section of this document.

Configure Apache Tomcat

The following instructions are known to work for Tomcat 7.0.27. If you need to install Tomcat, please go to the Tomcat homepage. The instructions below refer to the $CATALINA_HOME directory, which is the directory of your tomcat installation.

Put jar files in the classpath

Place the jarfiles in the lib directory of the Eureka! distribution in your Tomcat installation's $CATALINA_HOME/lib directory. Restart Tomcat if it is already running.

Configure the context.xml

Update the Apache Tomcat configuration to use the appropriate users and passwords to connect to the database. The file that contains the information is $CATALINA_HOME/conf/context.xml. Replace the SERVICE_PASSWORD, BACKEND_PASSWORD, DB_HOST, DB_NAME, and MAIL_SERVER placeholders in the file. Use the passwords previously chosen for the eurekaservice and eurekabackend users. The DB_HOST and DB_NAME placeholders represent the hostname and database service name in which the users where created previously. The MAIL_SERVER placeholder should be the fully qualified name of an SMTP host that the software can use to deliver emails to the system administrator and users. The following code snippet shows the main contents of the file:

<Resource name="jdbc/EurekaService" auth="Container"
 type="javax.sql.DataSource"
 driverClassName="oracle.jdbc.OracleDriver"
 factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
 url="jdbc:oracle:thin:@DB_HOST:1521:DB_NAME"
 username="eurekaservice" password="SERVICE_PASSWORD"
 initialSize="1" maxActive="3" maxIdle="1" minIdle="1"
 maxWait="-1"/>
<Resource name="jdbc/EurekaBackend" auth="Container"
 type="javax.sql.DataSource"
 driverClassName="oracle.jdbc.OracleDriver"
 factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
 url="jdbc:oracle:thin:@DB_HOST:1521:DB_NAME"
 username="eurekabackend" password="BACKEND_PASSWORD"
 initialSize="1" maxActive="3" maxIdle="3" minIdle="1"
 maxWait="-1"/>
<Resource name="mail/Session" auth="Container"
 type="javax.mail.Session"
 mail.smtp.host="MAIL_SERVER"
 mail.from="Eureka! Admin <no-reply@MAIL_SERVER>" />

If you choose to use BioPortal as a knowledge source in your Eureka! installation, please also add the following snippet to the context.xml file, replacing the file location in the url attribute to match where the h2 database is located:

<Resource name="jdbc/BioPortalDS" auth="Container"
 type="javax.sql.DataSource" driverClassName="org.h2.Driver"
 factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
 url="jdbc:h2:file:/etc/eureka/ontologies/bioportal"
 username="sa" password=""
 initialSize="1" maxActive="15" maxIdle="1" minIdle="1"
 maxWait="-1"/>
Eureka! Authentication

Eureka! uses jasig CAS for authentication.

In order to use CAS, the Tomcat server MUST be configured to use HTTPS connections for security reasons. The CAS server will refuse to authenticate users if the connection is made using the plain HTTP protocol. The following steps will enable SSL encryption (HTTPS connections) for Tomcat.

For additional information about setting up HTTPS for Tomcat, please see the please consult the Tomcat documentation.

  • Please make sure that Tomcat is shut down before making the following changes.

  • First, generate a keystore to be used by Tomcat to encrypt the data. To generate a keystore, use the keytool command, provided by the JDK. Use localhost as the name attribute when requested.

    ${JAVA_HOME}/bin/keytool -genkey -alias tomcat -keyalg RSA -keystore ${CATALINA_HOME}/conf/tomcat.keystore
    
  • Update the ${CATALINA_HOME}/conf/server.xml file to enable the JSSE method for HTTPS, and name the keystore file to use. Replace @PASSWORD@ with the keystore password used when creating the keystore.

    change
    <Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
      maxThreads="150" scheme="https" secure="true"
      clientAuth="false" sslProtocol="TLS" />
    
    to        
    <Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol" SSLEnabled="true"
      keystoreFile="${catalina.base}/conf/tomcat.keystore" keystorePass="@PASSWORD@"
      maxThreads="150" scheme="https" secure="true"
      clientAuth="false" sslProtocol="TLS" />
    
  • Update the central JDK keystore by adding the newly created keystore. This step is necessary to ensure that the various applications are able to communicate via HTTPS. If the central JDK keystore is not updated, the client side of the communication will not accept the certificate sent by the server side. The default password for the cacerts keystore is changeit. The source password will be the one provided when creating the tomcat.keystore file earlier.

    ${JAVA_HOME}/bin/keytool -importkeystore -srckeystore ${CATALINA_HOME}/conf/tomcat.keystore -srcalias tomcat -desckeystore ${JAVA_HOME}/jre/lib/security/cacerts
    
  • Finally, deploy the cas-server-<version_number>.war file in the lib/ directory of the distribution to the Tomcat installation. The war file is a customized version of CAS, intended to work seamlessly with a Eureka! install.

  • Start up Tomcat. When using the ‘Login’ link from the Eureka! main page, the user will now be redirected to CAS for authentication. On successful authentication, the user will be redirected back to the requested page.

Specify Java VM options

The default settings for the VM are insufficient for Eureka!. We use the following, which is specified in your Tomcat installation's $CATALINA_HOME/bin/setenv.sh file:

...
JAVA_OPTS="-Xms1024m -Xmx4096m -XX:MaxPermSize=256m"
...
Specify Java system properties

If the server on which you are installing Eureka! runs Linux, is headless and lacks entropy generation hardware, add the following to your Tomcat installation’s $CATALINA_HOME/bin/setenv.sh file:

...
CATALINA_OPTS="... -Djava.security.egd=file:///dev/urandom ..."
...

In particular, the Oracle JDBC driver may hang occasionally when establishing a connection without this setting.

If any of your data sources are a large Oracle database, and Eureka! will need to connect to it through a firewall, we recommend a few configuration settings.

First, add the following to your Tomcat installation's $CATALINA_HOME/bin/setenv.sh file to make the Oracle database driver throw an exception if the database connection drops:

...
CATALINA_OPTS="... -Doracle.jdbc.ReadTimeout=3600000 ..."
...

The value is in milliseconds.

Second, if you’re on Linux, avail yourself of the TCP keepalive feature, which will probe TCP connections periodically. The probing will keep the firewall from dropping database connections. Execute the following at the command line:

sudo sysctl -w net.ipv4.tcp_keepalive_time=1200
sudo sysctl -w net.ipv4.tcp_keepalive_intvl=180

Then, restart network services for the changes to take effect. The values are in seconds. To tell the Oracle JDBC driver to use keepalive, use net descriptor to connect to the database and specify the ENABLE=BROKEN parameter in the DESCRIPTION clause in the connect descriptor.

Setup i2b2

Set up database for i2b2

Eureka! requires an i2b2 database to function correctly. If your organization does not already have an i2b2 instance to load data to, the following steps will create the necessary users, tables, procedures, etc.

i2b2 Hive Setup

Create the i2b2 hive user. Please substitute PASSWORD with a secure password.

create user i2b2hive identified by "PASSWORD"
default tablespace users
quota 1000M on users
temporary tablespace temp;

Grant appropriate privileges to the hive user.

grant create session to i2b2hive;
grant create table to i2b2hive;
grant create view to i2b2hive;
grant create any index to i2b2hive;
grant create public synonym to i2b2hive;
grant drop public synonym to i2b2hive;
grant create sequence to i2b2hive;
grant create procedure to i2b2hive;
grant create any type to i2b2hive;
grant alter any type to i2b2hive;
grant drop any type to i2b2hive;
grant execute any type to i2b2hive;
grant under any type to i2b2hive;
grant create any trigger to i2b2hive;
grant alter any trigger to i2b2hive;
grant drop any trigger to i2b2hive;

Configure i2b2 Hive data upload process.

Where $I2B2_HOME is the location of your i2b2 download, edit the $I2B2_HOME/edu.harvard.i2b2.data/Release_1-5/NewInstall/Hivedata/db.properties file to specify database properties. The following snippet shows the contents of the file. Edit the DB_HOST, DB_NAME placeholders to suit your environment. The PASSWORD placeholder should be replaced with the password selected in the previous step.

db.type=oracle
db.username=i2b2hive
db.password=PASSWORD
db.server=DB_HOST:1521:DB_NAME
db.driver=oracle.jdbc.driver.OracleDriver
db.url=
jdbc:oracle:thin:@DB_HOST:1521:DB_NAME

Create the i2b2 Hive tables. Run the following ant command to create the database tables needed by the i2b2 Hive module.

cd $I2B2_HOME/edu.harvard.i2b2.data/Release_1-5/NewInstall/Hivedata/
ant -f data_build.xml create_hivedata_tables_release_1-5

Insert seed data for the i2b2 Hive module using the following ant command.

cd $I2B2_HOME/edu.harvard.i2b2.data/Release_1-5/NewInstall/Hivedata/
ant -f data_build.xml db_hivedata_load_data
i2b2 Project Management Cell Setup
Create the i2b2 Project Management (PM) user. Please substitute PASSWORD with a secure password.

create user i2b2pm identified by "PASSWORD"
default tablespace users
quota 1000M on users
temporary tablespace temp;
Grant appropriate privileges to the PM user.

grant create session to i2b2pm;
grant create table to i2b2pm;
grant create view to i2b2pm;
grant create any index to i2b2pm;
grant create public synonym to i2b2pm;
grant drop public synonym to i2b2pm;
grant create sequence to i2b2pm;
grant create procedure to i2b2pm;
grant create any type to i2b2pm;
grant alter any type to i2b2pm;
grant drop any type to i2b2pm;
grant execute any type to i2b2pm;
grant under any type to i2b2pm;
grant create any trigger to i2b2pm;
grant alter any trigger to i2b2pm;
grant drop any trigger to i2b2pm;
i2b2 PM Setup

Configure the i2b2 PM data upload process.

Edit the $I2B2_HOME/edu.harvard.i2b2.data/Release_1-5/NewInstall/Pmdata/db.properties file to specify database properties. The following code snippet shows the contents of the file. Edit the DB_HOST, DB_NAME placeholders to suit your environment. The PASSWORD placeholder should be replaced with the password selected in the previous step.

db.type=oracle
db.username=i2b2pm
db.password=PASSWORD
db.server=DB_HOST:1521:DB_NAME
db.driver=oracle.jdbc.driver.OracleDriver
db.url=jdbc:oracle:thin:@DB_HOST:1521:DB_NAME

Create the i2b2 PM tables and triggers by running the following ant command:

cd $I2B2_HOME/edu.harvard.i2b2.data/Release_1-5/NewInstall/Pmdata/
ant -f data_build.xml create_pmdata_tables_release_1-5
ant -f data_build.xml create_triggers_release_1-5

Insert the seed data for the i2b2 PM module:

cd $I2B2_HOME/edu.harvard.i2b2.data/Release_1-5/NewInstall/Pmdata/
ant -f data_build.xml db_pmdata_load_data

Configure i2b2

In order to use i2b2, configuration files must be updated to inform i2b2 of the new users and passwords. The i2b2 install can be found in the $JBOSS_HOME/default/server/default directory. Within that directory, the deploy and conf sub-directories both contain files relevant to i2b2.

Configure Hive data source

The i2b2hive data source is configured in the following files:

$JBOSS_HOME/default/server/default/deploy/work-ds.xml
$JBOSS_HOME/default/server/default/deploy/ont-ds.xml
$JBOSS_HOME/default/server/default/deploy/crc-jms-ds.xml
$JBOSS_HOME/default/server/default/conf/crcloaderapp/CRCLoaderApplicationContext.xml
$JBOSS_HOME/default/server/default/conf/crcapp/CRCApplicationContext.xml

See the code snippets below for the contents of the file. Update the DB_HOST and DB_NAME placeholders to suit your environment. The PASSWORD placeholder should be replaced with the password chosen for the i2b2hive user in the previous section.

.deploy/work-ds.xml:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>WorkplaceBootStrapDS</jndi-name>
<driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
<connection-url>jdbc:oracle:thin:@DB_HOST:1521:DB_NAME</connection-url>
<user-name>i2b2hive</user-name>
<password>PASSWORD</password>
</local-tx-datasource>
</datasources>

.deploy/ont-ds.xml:

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>OntologyBootStrapDS</jndi-name>
<driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
<connection-url>jdbc:oracle:thin:@DB_HOST:1521:DB_NAME</connection-url>
<user-name>i2b2hive</user-name>
<password>PASSWORD</password>
</local-tx-datasource>
</datasources>

.deploy/crc-jms-ds.xml

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>DefaultDS</jndi-name>
<connection-url>jdbc:oracle:thin:@DB_HOST:1521:DB_NAME</connection-url>
<driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
<user-name>i2b2hive</user-name>
<password>PASSWORD</password>
<idle-timeout-minutes>1</idle-timeout-minutes>
<exception-sorter-class-name>
org.jboss.resource.adapter.jdbc.vendor.OracleExceptionSorter
</exception-sorter-class-name>
<metadata>
<type-mapping>Oracle9i</type-mapping>
</metadata>
</local-tx-datasource>
</datasources>

.conf/crcloaderapp/CRCLoaderApplicationContext.xml:

...
<bean id="LoaderLookupDS"
class="org.apache.commons.dbcp.BasicDataSource"
destroy-method="close">
<property name="driverClassName"
value="oracle.jdbc.driver.OracleDriver"/>
<property name="url"
value="jdbc:oracle:thin:@DB_HOST:1521:DB_NAME"/>
<property name="username" value="i2b2hive"/>
<property name="password" value="PASSWORD"/>
</bean>
...

.conf/crcapp/CRCApplicationContext.xml:

...
<bean id="CRCDataSourceLookup"
class="org.apache.commons.dbcp.BasicDataSource"
destroy-method="close">
<property name="driverClassName"
value="oracle.jdbc.driver.OracleDriver"/>
<property name="url"
value="jdbc:oracle:thin:@DB_HOST:1521:DB_NAME"/>
<property name="username" value="i2b2hive"/>
<property name="password" value="PASSWORD"/>
</bean>
...
Configure Project Management datasource

The project management datasource is configured in the $JBOSS_HOME/default/server/default/deploy/pm-ds.xml file. Replace the DB_HOST and DB_NAME placeholders to suit your environment. The PASSWORD placeholder should be replaced with the password previously chosen for the i2b2pm user.

<?xml version="1.0" encoding="UTF-8"?>
<datasources>
<local-tx-datasource>
<jndi-name>PMBootStrapDS</jndi-name>
<driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
<connection-url>jdbc:oracle:thin:@DB_HOST:1521:DB_NAME</connection-url>
<user-name>i2b2pm</user-name>
<password>PASSWORD</password>
</local-tx-datasource>
</datasources>

Customize Eureka! configuration

Eureka! has a set of configurable properties that controls settings that are likely to be specific to a deployment. The built-in fallback values for these properties may be overridden in two places:

  • An application.properties file may be placed in the Eureka configuration directory. This is called the default configuration file. It is a standard Java properties file.
  • A properties file with the pathname specified with the eureka.config.file system property. This is called the user configuration file. It also is a standard Java properties file.

The default configuration file overrides the fallback values. The user configuration file overrides property values in the default configuration files. You only need to specify the values in either the default or the user configuration file that you want to be different from the fallback values.

Below is the list of configurable properties with their fallback values:

Property name Description Fallback value
eureka.webapp.url (new in 1.6.1!) The URL of the front-end webpage. It currently is used by the email generator to produce a URL for new users to send in the activation message. Auto-generated
eureka.etl.url The URL of the Protempa ETL layer. http://localhost:8080/eureka-protempa-etl
eureka.services.i2b2.adminuser If you have a single i2b2 deployment to which all ETL jobs go, specify an i2b2 admin user. Eureka! uses this to keep the i2b2 password synchronized with the Eureka! password. i2b2
eureka.services.i2b2.adminpassword

If you have a single i2b2 deployment to which all ETL jobs go, specify the above i2b2 admin user's password. Eureka! uses this to keep the i2b2 password synchronized with the Eureka! password.

demouser
eureka.services.i2b2.domain If you have a single i2b2 deployment to which all ETL jobs go, specify the i2b2 deployment's domain. The value of this property should be the value of the domain_name field in the i2b2 admin web page's Domains page (select PM Navigation > Manage Hive > Domains). Eureka! uses this to keep the i2b2 password synchronized with the Eureka! password. i2b2demo
eureka.services.i2b2.url If you have a single i2b2 deployment to which all ETL jobs go, specify the i2b2 deployment's project management cell's REST URL. Eureka! uses this to keep the i2b2 password synchronized with the Eureka! password. http://localhost:9090/i2b2/rest/PMService/getServices
eureka.services.email.from

The email address in the From header of email sent from the Eureka! services layer. If not specified, Eureka! will try using the "mail.from" property specified in the context.xml file. If not set, the "mail.user" and "mail.host" properties will be tried. If those are not set, the "user.name" property in combination with the hostname of the machine are tried. If all else fails, Eureka! will attempt to construct a "noreply" email address from the hostname of the machine on which the services layer is running. By default it is not specified.

Auto-generated
eureka.services.email.verify.subject The subject of the account registration verification email. Eureka! Clinical Analytics Registration Verification
eureka.services.email.activation.subject The subject of the account activation email. Eureka! Clinical Analytics Account Activation
eureka.services.email.password.subject The subject of the password changed email. Password changed on Eureka! Clinical Analytics
eureka.services.email.reset.subject The subject of the password reset email. Password reset on Eureka! Clinical Analytics
eureka.services.support.email The user support email address that appears in the user interface and emails sent to users by Eureka!. If you are not Emory and are hosting your own instance of Eureka!, you must change this! help@eurekaclinical.org
eureka.services.url The URL of the Eureka! services layer. It currently is used by the email generator to produce a URL for new users to send a verification code. If not specified, Eureka! tries to autocompute the URL by concatenating the internet address of the server and the port number on which the services layer is listening, like http://HOSTNAME:port/eureka-services. If this does not produce the desired results, set this property with the URL you want external users to use. Auto-generated
eureka.services.jobpool.size The maximum number of ETL jobs that can be executed in parallel. 5
eureka.services.registration.timeout Time in hours that users will have to verify their account registration. 72
eureka.services.defaultprops Whitespace-separated list of the root nodes of the system data elements displayed in the data element editor.

Encounter \
ICD9:Diagnoses \
ICD9:Procedures \
CPTCode \
LAB:LabTest \
MED:medications \
VitalSign \
READMISSIONS:EncounterWithSubsequent30DayReadmission \
READMISSIONS:SecondReadmit \
READMISSIONS:FrequentFlierEncounter \
READMISSIONS:Chemotherapy180DaysBeforeSurgery \
READMISSIONS:Chemotherapy365DaysBeforeSurgery \
READMISSIONS:Encounter90DaysEarlier \
READMISSIONS:Encounter180DaysEarlier \
DISEASEINDICATOR:MyocardialInfarction \
READMISSIONS:SecondMI \
DISEASEINDICATOR:UncontrolledDiabetes \
DISEASEINDICATOR:EndStageRenalDisease \
DISEASEINDICATOR:Obesity \
ERATCancer \
ERATCKD \
ERATCOPD \
ERATDiabetes \
ERATHF \
ERATHxTransplant \
ERATPulmHyp \
ERATStroke \
DISEASEINDICATOR:MethicillinResistantStaphAureusEvent \
DISEASEINDICATOR:SickleCellAnemiaEvent \
DISEASEINDICATOR:SickleCellCrisisEvent \
DISEASEINDICATOR:ThrombocytopeniaEvent \
DISEASEINDICATOR:MetastasisEvent \
DISEASEINDICATOR:HypertensionEvent

Configure Apache HTTPD for SSL

While not strictly needed, you may wish to install the Apache web server and have users access Eureka! through it (see http://httpd.apache.org). The installation of Apache's web server is beyond the scope of this document. If you use Linux, there likely is a version of Apache available through your distribution’s package manager.

Because Eureka! deals with sensitive data (such as medical records), and due to the use of CAS as the authentication mechanism, the use of SSL encryption for HTTP (HTTPS) to communicate with the web browser is required. In order for HTTPS to work correctly, an SSL certificate must be generated. While it is recommended that you get a certificate assigned by an actual certificate authority, the free option is to generate a self-signed certificate.

The procedure for generating an SSL certificate is operating system dependent, but for most Linux and Unix installations the following commands will suffice. The certificate will be valid for one year (365 days). Please replace the HOST_NAME placeholder with the fully qualified domain name of your Eureka! server.

cd /root
openssl req -newkey rsa:2048 -keyout HOST_NAME.key -nodes -x509 -days 365 -out HOST_NAME.crt

After creation, copy the SSL certificate and key to your HTTPD installation. Please replace the HOST_NAME placeholder with the fully qualified domain name of the Eureka! host.

cd /root
cp HOST_NAME.key /etc/pki/tls/private/HOST_NAME.key
cp HOST_NAME.crt /etc/pki/tls/certs/HOST_NAME.crt

Once the files are in the proper location, Apache HTTPD must be configured to use the files. The configuration is done in the conf.d/ssl.conf file in your HTTPD installation. Simply update the SSLCertificateFile and SSLCertificateKeyFile parameters in the file. Please replace the HOST_NAME placeholder with the fully qualified domain name of the Eureka! host.

...
SSLCertificateFile /etc/pki/tls/certs/HOST_NAME.crt
SSLCertificateKeyFile /etc/pki/tls/private/HOST_NAME.key
...

User account setup

You are done with the installation! To add users, see the User Account Setup page. For usage instructions, see the Getting Started Guide.