🗄️HAPI FHIR Server

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

Note that this project is specifically intended for end users of the HAPI FHIR JPA server module (in other words, it helps you implement HAPI FHIR, it is not the source of the library itself). If you are looking for the main HAPI FHIR project, see here: https://github.com/hapifhir/hapi-fhir

Need Help? Please see: https://github.com/hapifhir/hapi-fhir/wiki/Getting-Help

Configuration

To run the application, you should pass the necessary configuration via environment properties. To achieve this, create a .env file and pass your own values for the following properties.

Note: Please paste the .env file inside the specified directory.

/hapi-fhir-jpaserver-starter/

.env file

APP_VALIDATE_TOKEN_API={{ip}}/auth-service/authenticate
FHIR_DATASOURCE_URL=jdbc:postgresql://{{ip}}:5432/spice_open_source_fhir?serverTimezone=UTC
FHIR_DATASOURCE_USERNAME={{username}}
FHIR_DATASOURCE_PASSWORD={{password}}

Note: The values for the environmental variables should be changed based on the chosen service.

.env

The .env file is used to store environment variables for the project. These variables are used to configure the application and contain sensitive information such as passwords, API keys, and other credentials.

Please note that the .env file should never be committed to version control, as it contains sensitive information that should not be shared publicly. Instead, you should add the .env file to your .gitignore file to ensure that it is not accidentally committed.

To use the application, you will need to create a .env file in the root directory of the project and add the necessary environment variables. You can refer to the above file for an example of the required variables and their format.

The values provided in the instructions are for demonstration purposes only and will not work as-is. You will need to replace them with actual values that are specific to your environment.

Note: After checking out the project, please ensure that you update the relevant properties and values in env.example, and then rename it to .env.

.env description

APP_VALIDATE_TOKEN_API: This property specifies the authentication endpoint from the Spice Auth service.

FHIR_DATASOURCE_URL: This property contains the JDBC connection URL for the PostgreSQL database server with the server timezone set to UTC, with the database name.

FHIR_DATASOURCE_USERNAME: This property contains the username used to connect to the PostgreSQL database server.

FHIR_DATASOURCE_PASSWORD: This property contains the password to connect to the PostgreSQL database server.

Deployment

Run the following commands in the below path

Build a clean-install using maven /hapi-fhir-jpaserver-starter

mvn clean install -DskipTests

Build docker images by the following command

docker-compose build

Once the images are built, run the docker containers by the following docker command

docker-compose up

Server will then be accessible at http://{{ip}}:8080/

Enabling Subscriptions

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

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

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

• hapi.fhir.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/websocket

Enabling Clinical Reasoning

Set hapi.fhir.cr_enabled=true in the application.yaml file to enable Clinical Quality Language on this server.

Enabling MDM (EMPI)

Set hapi.fhir.mdm_enabled=true in the application.yaml file to enable MDM on this server. The MDM matching rules are configured in mdm-rules.json. The rules in this example file should be replaced with actual matching rules appropriate to your data. Note that MDM relies on subscriptions, so for MDM to work, subscriptions must be enabled.

Using Elasticsearch

By default, the server will use embedded lucene indexes for terminology and fulltext indexing purposes. You can switch this to using lucene by editing the properties in application.yaml

For example:

elasticsearch.enabled=true
elasticsearch.rest_url=localhost:9200
elasticsearch.username=SomeUsername
elasticsearch.password=SomePassword
elasticsearch.protocol=http
elasticsearch.required_index_status=YELLOW
elasticsearch.schema_management_strategy=CREATE

Enabling LastN

Set hapi.fhir.lastn_enabled=true in the application.yaml file to enable the $lastn operation on this server. Note that the $lastn operation relies on Elasticsearch, so for $lastn to work, indexing must be enabled using Elasticsearch.

Enabling Resource to be stored in Lucene Index

Set hapi.fhir.store_resource_in_lucene_index_enabled in the application.yaml file to enable storing of resource json along with Lucene/Elasticsearch index mappings.

Changing cached search results time

It is possible to change the cached search results time. The option reuse_cached_search_results_millis in the application.yaml is 6000 miliseconds by default. Set reuse_cached_search_results_millis: -1 in the application.yaml file to ignore the cache time every search.

Build the distroless variant of the image (for lower footprint and improved security)

The default Dockerfile contains a release-distroless stage to build a variant of the image using the gcr.io/distroless/java-debian10:11 base image:

docker build --target=release-distroless -t hapi-fhir:distroless .

Note that distroless images are also automatically built and pushed to the container registry, see the -distroless suffix in the image tags.

Adding custom operations

To add a custom operation, refer to the documentation in the core hapi-fhir libraries here.

Within hapi-fhir-jpaserver-starter, create a generic class (that does not extend or implement any classes or interfaces), add the @Operation as a method within the generic class, and then register the class as a provider using RestfulServer.registerProvider().

Runtime package install

It's possible to install a FHIR Implementation Guide package (package.tgz) either from a published package or from a local package with the $install operation, without having to restart the server. This is available for R4 and R5.

This feature must be enabled in the application.yaml (or docker command line):

hapi:
  fhir:
    ig_runtime_upload_enabled: true

The $install operation is triggered with a POST to [server]/ImplementationGuide/$install, with the payload below:

{
  "resourceType": "Parameters",
  "parameter": [
    {
      "name": "npmContent",
      "valueBase64Binary": "[BASE64_ENCODED_NPM_PACKAGE_DATA]"
    }
  ]
}

Enable OpenTelemetry auto-instrumentation

The container image includes the OpenTelemetry Java auto-instrumentation Java agent JAR which can be used to export telemetry data for the HAPI FHIR JPA Server. You can enable it by specifying the -javaagent flag, for example by overriding the JAVA_TOOL_OPTIONS environment variable:

docker run --rm -it -p 8080:8080 \
  -e JAVA_TOOL_OPTIONS="-javaagent:/app/opentelemetry-javaagent.jar" \
  -e OTEL_TRACES_EXPORTER="jaeger" \
  -e OTEL_SERVICE_NAME="hapi-fhir-server" \
  -e OTEL_EXPORTER_JAEGER_ENDPOINT="http://jaeger:14250" \
  docker.io/hapiproject/hapi:latest

You can configure the agent using environment variables or Java system properties, see https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/ for details.