Skip to content

Deployment

Jump to bottom
JP edited this page Jun 8, 2022 · 28 revisions

Overview

The cqf-ruler is built as an executable war file (using Spring Boot) and also packaged as a Docker container. This provides 3 ways to host server:

  • Running the war directly
  • Using Docker
  • Java Application Servers

The cqf-ruler server is capable of running multiple versions of FHIR but only one at a time is supported. If you need to support multiple versions of FHIR simultaneously you must start multiple instances of the cqf-ruler, each with the appropriate configuration.

The two most commonly used configuration parameters are:

Parameter Default Options
hapi.fhir.fhir_version R4 DSTU2, DSTU3, R4, R5
server_address http://localhost:8080 any valid url

This means the cqf-ruler will start running at localhost:8080 in FHIR R4 mode by default.

See Configuration for more details.

Executable war

Run the war using:

java -jar -Dhapi.fhir.fhir_version=DSTU3 cqf-ruler-server-*.war

The -DXXXX parameter allows you to set Environment variables. See Configuration for more information.

Docker

The CQF Ruler is also available in the form of a Linux Docker container that contains an instance of the CQF Ruler running in a Jetty server. This is a publicly available container - alphora/cqf-ruler.

With a Docker instance installed that supports Linux containers (see the Docker documentation here for installation instructions), you can install and run the container by issuing the following Docker commands at the command line:

docker pull alphora/cqf-ruler
docker run -p 8080:8080 alphora/cqf-ruler

This should pull the latest version of the container - alphora/cqf-ruler - and start the instance with the CQF Ruler being exposed on port 8080.

Docker used the -e flag to set environment variables.

docker run -p 8081:8080 \
-e SERVER_ADDRESS="http://localhost:8081/fhir" \ 
alphora/cqf-ruler

Additionally, if you need advanced configuration, you can create a custom application.yaml file and mount it into the container.

docker run -p 8080:8080 \
-e SPRING_CONFIG_LOCATION=file:/config/application.yaml
-v /path/to/custom/application.yaml:config/application.yaml \
alphora/cqf-ruler

Please note that some container runtimes such as podman do not support volume mounts for security reasons. In these instances you must set the configuration via environment variables.

Application Servers

The cqf-ruler server is packaged as a runnable war file. Java app servers such as Jetty, Tomcat, etc. can use this file to run the cqf-ruler application.

The setup for each server is specific to that particular server, so please see the appropriate documentation for your server.

NOTE: If these deployment options are not satisfactory for your system, please raise an issue in this repository and we will make every effort to come up with a solution. Additionally, contributions are always welcomed and encouraged.

System Hardware Requirements

The cqf-ruler should be given a minimum of 2 cores and 4 GB of ram based on practical experience. Fewer cores or less ram will result in poor performance.

Configuration

The cqf-ruler follows the configuration pattern established by the upstream hapi-fhir-jpaserver-starter project and uses a standard approach provided by the Spring framework to read configuration from environment variables. This means that nearly all configuration can simply be done with flags provided to the cqf-ruler container launch and that all the configuration documentation available on the hapi-fhir wiki applies equally to the ruler.

Environment Variables

Spring supports reading configuration from environment variables. As an example, to run the cqf-ruler from a docker container in dstu3 mode, use the following command:

docker run -e hapi.fhir.fhir_version=DSTU3 -p 8080:8080 alphora/cqf-ruler

Spring Config File

Alternatively, the configuration can be put in its own application.yaml file and you can tell the cqf-ruler to look for the configuration by specifying an environment variable:

SPRING_CONFIG_LOCATION=file:/some/directory/for/the/application.yaml

NOTE: The application.yaml file only configures the cqf-ruler application. If you're using an application server as opposed to Spring Boot, your application server (jetty, tomcat, etc) must be configured to serve the application at a domain, port, and path that matches the application configuration.

CQL Logging

The cqf-ruler supports debug logging of the embedded CQL engine. To enable this use the following configuration property:

hapi.fhir.cql.engine.debug_logging_enabled=true
Clone this wiki locally