# 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: Need Help? Please see: ## 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** ```properties 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` ```sh mvn clean install -DskipTests ``` Build docker images by the following command ```sh docker-compose build ``` Once the images are built, run the docker containers by the following docker command ```sh 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](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/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): ## Enabling Clinical Reasoning Set `hapi.fhir.cr_enabled=true` in the [application.yaml](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/application.yaml) file to enable [Clinical Quality Language](https://cql.hl7.org/) on this server. ## Enabling MDM (EMPI) Set `hapi.fhir.mdm_enabled=true` in the [application.yaml](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/application.yaml) file to enable MDM on this server. The MDM matching rules are configured in [mdm-rules.json](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/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](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/application.yaml) For example: ```properties 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](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/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](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/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](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/application.yaml) is 6000 miliseconds by default. Set `reuse_cached_search_results_millis: -1` in the [application.yaml](https://github.com/hapifhir/hapi-fhir-jpaserver-starter/blob/master/src/main/resources/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: ```sh 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](https://hapifhir.io/hapi-fhir/docs/server_plain/rest_operations_operations.html). 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): ```yaml hapi: fhir: ig_runtime_upload_enabled: true ``` The `$install` operation is triggered with a POST to `[server]/ImplementationGuide/$install`, with the payload below: ```json { "resourceType": "Parameters", "parameter": [ { "name": "npmContent", "valueBase64Binary": "[BASE64_ENCODED_NPM_PACKAGE_DATA]" } ] } ``` ## Enable OpenTelemetry auto-instrumentation The container image includes the [OpenTelemetry Java auto-instrumentation](https://github.com/open-telemetry/opentelemetry-java-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: ```sh 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 for details.