🗄️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
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
Build docker images by the following command
Once the images are built, run the docker containers by the following docker command
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 serverhapi.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:
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:
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):
The $install
operation is triggered with a POST to [server]/ImplementationGuide/$install
, with the payload below:
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:
You can configure the agent using environment variables or Java system properties, see https://opentelemetry.io/docs/instrumentation/java/automatic/agent-config/ for details.
Last updated