Skip to content
No description, website, or topics provided.
Branch: master
Clone or download
Latest commit 5bb2790 Jun 18, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
src Merge branch 'master' of Jun 10, 2019
.travis.yml Add travis CI support Feb 11, 2019
Dockerfile fixing Dockerfile Jun 17, 2019
LICENSE Initial commit Jul 26, 2018 Updated MySQL configuration instructions to highlight the dependence … May 23, 2019 Initial commit Jul 26, 2018
pom.xml Merge branch 'master' of Jun 10, 2019
pom.xml.orig Merge branch 'master' of Feb 7, 2019

HAPI-FHIR Starter Project

This project is a complete starter project you can use to deploy a FHIR server using HAPI FHIR JPA.


In order to use this sample, you should have:

  • This project checked out. You may wish to create a GitHub Fork of the project and check that out instead so that you can customize the project and save the results to GitHub.
  • Oracle Java (JDK) installed: Minimum JDK8 or newer.
  • Apache Maven build tool (newest version)

Running Locally

The easiest way to run this server is to run it directly in Maven using a built-in Jetty server. To do this, change src/main/resources/ server_address and server.base with the values commented out as For Jetty, use this and then execute the following command:

mvn jetty:run

Then, browse to the following link to use the server:



Much of this HAPI starter project can be configured using the properties file in src/main/resources/ By default, this starter project is configured to use Derby as the database.


To configure the starter app to use MySQL, instead of the default Derby, update the file to have the following:

  • datasource.driver=com.mysql.jdbc.Driver
  • datasource.url=jdbc:mysql://localhost:3306/hapi_dstu3
  • hibernate.dialect=org.hibernate.dialect.MySQL5InnoDBDialect

Because the integration tests within the project rely on the default Derby database configuration, it is important to either explicity skip the integration tests during the build process, i.e., mvn install -DskipTests, or delete the tests altogether. Failure to skip or delete the tests once you've configured MySQL for the datasource.driver, datasource.url, and hibernate.dialect as outlined above will result in build errors and compilation failure.

It is important to use MySQL5Dialect when using MySQL version 5+.

Customizing The Web Testpage UI

The UI that comes with this server is an exact clone of the server available at You may skin this UI if you'd like. For example, you might change the introductory text or replace the logo with your own.

The UI is customized using Thymeleaf template files. You might want to learn more about Thymeleaf, but you don't necessarily need to: they are quite easy to figure out.

Several template files that can be customized are found in the following directory:

Deploying to a Container

Using the Maven-Embedded Jetty method above is convenient, but it is not a good solution if you want to leave the server running in the background.

Most people who are using HAPI FHIR JPA as a server that is accessible to other people (whether internally on your network or publically hosted) will do so using an Application Server, such as Apache Tomcat or Jetty. Note that any Servlet 3.0+ compatible Web Container will work (e.g Wildfly, Websphere, etc.).

Tomcat is very popular, so it is a good choice simply because you will be able to find many tutorials online. Jetty is a great alternative due to its fast startup time and good overall performance.

To deploy to a container, you should first build the project:

mvn clean install

This will create a file called hapi-fhir-jpaserver.war in your target directory. This should be installed in your Web Container according to the instructions for your particular container. For example, if you are using Tomcat, you will want to copy this file to the webapps/ directory.

Again, browse to the following link to use the server (note that the port 8080 may not be correct depending on how your server is configured).


Running hapi-fhir-jpaserver-example in Tomcat from IntelliJ

Install Tomcat.

Make sure you have Tomcat set up in IntelliJ.

  • File->Settings->Build, Execution, Deployment->Application Servers
  • Click +
  • Select "Tomcat Server"
  • Enter the path to your tomcat deployment for both Tomcat Home (IntelliJ will fill in base directory for you)

Add a Run Configuration for running hapi-fhir-jpaserver-example under Tomcat

  • Run->Edit Configurations
  • Click the green +
  • Select Tomcat Server, Local
  • Change the name to whatever you wish
  • Uncheck the "After launch" checkbox
  • On the "Deployment" tab, click the green +
  • Select "Artifact"
  • Select "hapi-fhir-jpaserver-example:war"
  • In "Application context" type /hapi

Run the configuration.

  • You should now have an "Application Servers" in the list of windows at the bottom.
  • Click it.
  • Select your server, and click the green triangle (or the bug if you want to debug)
  • Wait for the console output to stop

Point your browser (or fiddler, or what have you) to http://localhost:8080/hapi/baseDstu3/Patient

It is important to use MySQL5Dialect when using MySQL version 5+.

Enabling Subscriptions

The server may be configured with subscription support by enabling properties in the file:

  • subscription.resthook.enabled - Enables REST Hook subscriptions, where the server will make an outgoing connection to a remote REST server

  • - Enables email subscriptions. Note that you must also provide the connection details for a usable SMTP server.

  • subscription.websocket.enabled - Enables websocket subscriptions. With this enabled, your server will accept incoming websocket connections on the following URL (this example uses the default context path and port, you may need to tweak depending on your deployment environment): ws://localhost:8080/hapi-fhir-jpaserver/websocket

You can’t perform that action at this time.