Skip to content

Deployment

Jump to bottom
JPercival edited this page May 5, 2020 · 28 revisions

General Configuration

The cqf-ruler generally reuses the hapi.properties file from the HAPI FHIR server for application configuration. There's some documentation of that file available in the README of HAPI FHIR JPA Server Starter Project.

Each distribution of the cqf-ruler includes an embedded default hapi.properties that configure the application's url to http://localhost:8080/cqf-ruler-dstu3 or http://localhost:8080/cqf-ruler-r4 depending on whether you are using the DSTU3 or R4 version of the cqf-ruler.

If you need to change the properties of the server, such as changing the base url, create a custom hapi.properties file with the appropriate configuration. Then edit your JAVA_OPTIONS to include:

-Dhapi.properties=/path/to/custom/hapi.properties

This will cause the cqf-ruler to use the custom properties you set. If, for example, you are using a server to run the ruler at http://my.example.org/cqf-ruler-dstu3/fhir, create a hapi.properties containing the following:

# This is the address that the FHIR server will report as its own address.
# If this server will be deployed (for example) to an internet accessible
# server, put the DNS name of that server here.
server_address=http://my.example.org/cqf-ruler-dstu3/fhir/

Then run the cqf-ruler with JAVA_OPTIONS=-Dhapi.properties=/path/to/custom/hapi.properties

NOTE: The hapi.properties file only configures the cqf-ruler application. Your application server (jetty, tomcat, etc) must be configured to serve the application at a domain, port, and path that matches the application configuration.

NOTE: Each instance of the cqf-ruler searches for hapi.properties configuration in the following order:

  • -Dhapi.properties.FHIR_VERSION=/path/to/custom/hapi.properties
    • e.g. -Dhapi.properties.R4=/path/to/custom/hapi.properties, -Dhapi.properties.DSTU3=/path/to/custom/hapi.properties
    • DSTU3 and R4 are CASE SENSITIVE
  • Dhapi.properties=/path/to/custom/hapi.properties
  • Embedded default properties

Jetty

The CQF Ruler is packaged with an embedded Jetty server, which can be easily started using the Maven Jetty plugin. The simplest example of spinning up the Jetty server can be done with the following command:

DSTU3: -mvn jetty:run -am --projects cqf-ruler-dstu3

R4: -mvn jetty:run -am --projects cqf-ruler-r4

After running that command the CQF Ruler will be available at the default endpoint: http://localhost:8080/cqf-ruler-dstu3/fhir or http://locahost:8080/cqf-ruler-r4/fhir.

You can change the port with the jetty.http.port property:

mvn -Djetty.http.port=8081 jetty:run -am --projects cqf-ruler-r4

It is possible to customize the endpoint using the protocolAndHost maven property:

mvn -DprotocolAndHost=http://measure.eval.kanvix.com jetty:run -am --projects cqf-ruler-r4

Or to run with custom hapi.properties:

mvn -Dhapi.properties=/some/custom/directory/hapi.properties jetty:run -am --projects cqf-ruler-r4

Tomcat

Build the CQF Ruler:

mvn -DskipTests package

Following the execution of that command, a two war files (cqf-ruler-dstu3.war and cqf-ruler-r4.war) will be available within the target directories of the cqf-ruler-dstu3 and cqf-ruler-r4 modules. Drop one (according to the FHIR version you require) or both war files into the "webapps" directory and start your Tomcat instance. The CQF Ruler will be available at the default endpoint(s): http://localhost:8080/cqf-ruler-dstu3/fhir and http://localhost:8080/cqf-ruler-r4/fhir.

Customizing the endpoint requires an additional configuration step to set the required system properties. The configuration step requires creating a setenv.sh (setenv.bat for Windows) file in the {TOMCAT_HOME}/bin directory with the system properties defined. The following is an example for Mac/Linux:

CATALINA_OPTS="${CATALINA_OPTS} -DprotocolAndHost=http://localhost:8080 -Dhapi.properties=/path/to/custom/hapi.properties

For Windows:

JAVA_OPTS=-DprotocolAndHost=http://localhost:8080 -Dhapi.properties=/path/to/custom/hapi.properties

If you need to configure both DSTU3 and R4 simultaneously, use the version specific hapi.properties properties:

CATALINA_OPTS="${CATALINA_OPTS} -DprotocolAndHost=http://localhost:8080 -Dhapi.properties.DSTU3=/path/to/custom/dstu3/hapi.properties -Dhapi.properties.R4=/path/to/custom/r4/hapi.properties

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 - contentgroup/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 contentgroup/cqf-ruler
docker run -p 8080:8080 contentgroup/cqf-ruler

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

The docker container runs two instances of the cqf-ruler side-by-side, one for DSTU3 and one for R4, exposing them at http://localhost:8080/cqf-ruler-dstu3 or http://localhost:8080/cqf-ruler-r4. For ease of configuration, the docker container exposes two environment variables for configuring the server address:

If you set either of those properties the docker container will generate the appropriate hapi.properties file and configure the cqf-ruler to use it on startup. For example, if you need to use a different port:

docker run -p 8081:8080 -e SERVER_ADDRESS_DSTU3="http://localhost:8081/cqf-ruler-dstu3/fhir" \ 
-e SERVER_ADDRESS_R4="http://localhost:8081/cqf-ruler-r4/fhir" contentgroup/cqf-ruler

Additionally, if you need more advanced configuration, you can create a custom hapi.properties file, mount it into the container, and configure the JAVA_OPTIONS variable. The same rules of precedence for selecting version specific hapi.properties files apply.

docker run -p 8080:8080 -e JAVA_OPTIONS=-Dhapi.properties=/var/lib/jetty/webapps/hapi.properties -v /path/to/custom/hapi.properties:/var/lib/jetty/webapps/hapi.properties contentgroup/cqf-ruler

NOTE: The path in the JAVA_OPTIONS refers to the path of the hapi.properties inside of the container, not the path on the local machine. The -v flag takes the form of -v /path/on/host:/path/in/container

*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.

Clone this wiki locally