HAPI FHIR Software for IHE Connectathons

These instructions direct you to build the HAPI FHIR software from original source code. There is a Dockerized version that would likely get you to the same place. Our original attempts with that version failed, but that might have been pilot error. We will document the steps that worked for us (NA 2020).

Create Postgres Databases

• Create empty HAPI-FHIR databases. The application assumes an empty Postgres database for each of the supported versions.
  • We discovered this through trial and error. There may be ways to only create the databases you need.
  • Later versions of the software might require different databases.
  • We use the postgres role with the password "postgres". You will see that in the section when you configure Tomcat. You can choose a different password and/or use better Postgres

psql -U postgres createdb fhirtest_dstu2

psql -U postgres createdb fhirtest_dstu3

psql -U postgres createdb fhirtest_r4

psql -U postgres createdb fhirtest_r5

Create Folders for Lucene Files

The software assumes folders have been created to hold Lucene data. The path to the folders is passed to the software when you configure Tomcat (next section). We created (and later referenced) these folders:

/opt/NA-2020/hapi-fhir-tomcat/lucene/dstu2

/opt/NA-2020/hapi-fhir-tomcat/lucene/dstu3

/opt/NA-2020/hapi-fhir-tomcat/lucene/r4

/opt/NA-2020/hapi-fhir-tomcat/lucene/r5

• The parent folder (/opt/NA-2020/hapi-fhir-tomcat) is arbitrary; you may pick a different folder.
• There is no requirement that the four folders (dstu2, dstu3, r4, r5) have a common parent. The configuration below points to each folder separately.

Install and Configure Tomcat

We used Tomcat Version 8.5.50 for NA 2020. After you install the Tomcat software, you need to add some configuration. We added these lines in bin/catalina.sh:

CATALINA_OPTS="-Dfhir.db.username=postgres $CATALINA_OPTS"

CATALINA_OPTS="-Dfhir.db.password=postgres $CATALINA_OPTS"

CATALINA_OPTS="-Dfhir.tdlpass=a,b $CATALINA_OPTS"

CATALINA_OPTS="-Dfhir.baseurl=http://fhir-read-write:8080/fhir/baseR4 $CATALINA_OPTS"

CATALINA_OPTS="-Dfhir.lucene.location.dstu2=/opt/NA-2020/hapi-fhir-tomcat/lucene/dstu2 -Dfhir.lucene.location.dstu3=/opt/NA-2020/hapi-fhir-tomcat/lucene/dstu3 -Dfhir.lucene.location.r4=/opt/NA-2020/hapi-fhir-tomcat/lucene/r4 -Dfhir.lucene.location.r5=/opt/NA-2020/hapi-fhir-tomcat/lucene/r5 $CATALINA_OPTS"

• Lines 1 and 2 set the username and password used to access the Postgres database. Make sure you are in alignment with how you configured Postgres.
• Line 3 was added because the software was throwing an exception without it (I believe). There did not seem to be any effect on the software itself if this value was used.
• Line 4 is needed for the application to know where the base URL is located.
  • fhir-read-write is the hostname that is known to this server and to users
  • /fhir needs to match the name of the war (fhir.war)
  • /baseR4 is for the R4 software. We only used R4 resources at NA 2020. Not sure what would change if you also needed DSTU3 resources.
• Line 5 gives the location of directories that are used to hold lucene files created by the application.
  • Synchronize with the folders created above.

Build the WAR File

• Clone a copy of the HAPI-FHIR server

git clone https://github.com/jamesagnew/hapi-fhir.git

• Checkout the appropriate branch or version. For NA 2020, we used v4.1.0. Your event may use a more recent version.

cd hapi-fhir

git checkout v4.1.0

• Modify source code

There are small changes necessary to configure the software. These are completed directly in the source code and not in a configuration file. Please see the section below.

• Build the war file

Use the mvn command to build the war file. You want to use the flag -DskipTests unless you want to wait a long time for the unit tests to complete.

mvn -DskipTests install

• Copy the war file to the tomcat server

cp hapi-fhir-jpaserver-uhnfhirtest/target/hapi-fhir-jpaserver.war $TOMCAT/webapps/fhir.war

• Create empty HAPI-FHIR databases.

The application assumes an empty Postgresql database for each of the supported versions.

psql -U postgres createdb fhirtest_dstu2

psql -U postgres createdb fhirtest_dstu3

psql -U postgres createdb fhirtest_r4

psql -U postgres createdb fhirtest_r5

• • We discovered this through trial and error. There may be ways to only create the databases you need.
  • Later versions of the software might require different databases.
  • We run postgres using "trust" security in the pg_hba.conf file. If you want a more secure system, you will have to determine the password scheme used by the software and/or lock down the database in other ways (say by host).

• Start the Tomcat server

cd $TOMCAT

chmod +x bin/*sh

./bin/startup.sh