Skip to content

Setting up for development

Jump to bottom
Lee Surprenant edited this page Sep 16, 2022 · 93 revisions

Prereqs

Java 11

The LinuxForHealth FHIR Server requires Java 11 or higher and has been tested with OpenJDK 11. To install Java on your system, we recommend downloading and installing OpenJDK 11 from https://adoptium.net.

Maven

The LinuxForHealth FHIR Server is a multi-module Maven project. Any recent version of Maven should work. Download from the Maven download site.

Git Tools

To download this repository or a fork, you should have Git Tools installed. Download and install from git-scm.

Docker

Optional: If you intend to use LinuxForHealth FHIR Server in a container or build the image. You can install Docker Desktop or another option is Rancher Desktop. You can find helpful information on using Rancher Desktop with the LinuxForHealth FHIR Server here.

Eclipse

Optional: Other IDEs / code editors may work for you, but most of the maintainers use Eclipse.

Note: do not attempt to mix the Liberty Developer Tools with Spring Boot tools - they appear to conflict.

Download Eclipse IDE for Enterprise Java and Web Developers and install the following plugins:

Once installed, navigate to Preferences and make the following changes:

  1. Validation -> uncheck the Build checkbox next to JSON Syntax Validator, JSON Validator, Open API 3.0 Validator, and XML Validator.

    This step speeds up workspace builds by avoiding needless validation of sample files. Manual validation can still be performed by right-clicking a file and choosing Validate.

  2. Import the Code Style Format Rules via Eclipse > Preferences... > Java > Code Style > Formatter > Import...

    The rules attempt to codify some of the preferences documented in our Style Guide, although the only one we enforce is favoring spaces over tabs. You will need to import the Style Guide for each unique Eclipse workspace.

  3. Configure 'General > Editors > Text Editors' with 'Insert spaces for tabs' (4 spaces).

  4. Import the Code Template Click Eclipse > Preference. Click on Java > Code Style > Code Template. Import the Template - Template.xml

You are now ready to build the code, setup Open Liberty and import the projects.

Build the code

Git fork and clone the LinuxForHealth FHIR repository following the GitHub Standard Fork & Pull Request Workflow. For instance, git clone git@github.com:<myuser>/FHIR.git where <myuser> is your GitHub user or GitHub organization.

Once cloned locally, execute the following from the root of the repository:

  1. mvn clean install -f fhir-examples

The fhir-examples project contains:

  • examples from the HL7 FHIR specification
  • minimal, complete-absent, and complete-mock examples generated from fhir-examples-generator

Since it rarely changes, we keep it out of the main build.

  1. mvn clean install -f fhir-parent

This command invokes the build with all of the tests. If you want to skip the tests, add -DskipTests. After the build completes, fhir-install/target will contain the zip installable.

  1. Optionally, once the build completes, you can build a docker image from the installable by running: docker build fhir-install.

Running with the Liberty Maven Plugin

The Liberty Maven Plugin provides a quick and easy way to run Liberty-based applications like the LinuxForHealth FHIR Server from Maven.

To run the server in Liberty's dev mode, perform the following steps.

Warning There is currently a Liberty Maven Plugin bug that prevents hot loading from working with our multi-module project.

Bootstrap the database

For Mac OSX / Linux environments, execute the build/derby-bootstrap.sh shell script to generate a derby database at the root of the project:

build/derby-bootstrap.sh

On Windows, you can manually run the fhir-persistence-schema commands from this script or create your own wrapper script.

Start the server

To start the server in dev mode, execute the following from the root of the project:

mvn liberty:dev -f fhir-server-webapp

You can confirm that the server is healthy (i.e. running, responding to requests, and able to connect to the database) via curl:

curl -k -i -u 'fhiruser:change-password' 'https://localhost:9443/fhir-server/api/v4/$healthcheck'

Import to your IDE / editor of choice

The LinuxForHealth FHIR Server team is using Eclipse; feel free to use anything you want while honoring the Style Guide and Code Template.

Importing to Eclipse

  1. Import the Projects - File > Import > Maven > Existing Maven Projects and M2Eclipse configures the projects. (import all projects from the repository).

  2. Delete the extraneous EAR projects for each project used in the FHIR server webapps. There is a Liberty Tools issue which leads to the automatic creation of extraneous. These projects are only generated a single time and should be deleted from your system (delete all EAR projects). Note, these may not appear until you add the war files to the Open Liberty server in Eclipse.

  3. If you import fhir-tools, you may be prompted to fix the m2e connector for maven-plugin-plugin. The error details are: Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-plugin-plugin:3.6.0:descriptor (execution: mojo-descriptor, phase: process-classes)

    • In this case, it is recommended you 'Setup Maven plugin connectors', and click Finish.

  4. If you are prompted to install the m2e connector for Checkstyle Plugin, please do install and setup. Plugin execution not covered by lifecycle configuration: org.apache.maven.plugins:maven-checkstyle-plugin:3.1.0:check (execution: default, phase: validate)

Running from Eclipse

To run the LinuxForHealth FHIR Server from Eclipse you must first install a Liberty Server. Due to special packaging requirements of the FHIR persistence layer, its simplest to "install" the Server to a local directory first, then Define a Server in eclipse and point it at the install location.

Installing the server

After building the project, navigate to fhir-install/target, unzip fhir-server-distribution.zip, and enter the directory; then

  1. From a terminal, execute ./install.sh <targetDir> or install.bat <targetDir> depending on your platform. This will install OpenLiberty to that location with a single server named "defaultServer".
  2. From eclipse, create a New Server, select IBM/Liberty Server, Choose an existing installation, and point it at the server you just installed - <targetDir>/wlp.
  3. Right-click on the Liberty Server > Add and Remove > Add all the War files to the server. Note, I added without removing the ghosted applications.
  4. If needed, update your Liberty server's server.xml with the master copy that is under fhir-server-webapp/src/main/liberty/config. This is needed if eclipse decides to rewrite the webApplication element which can lose our common library reference around line 70.
  5. Create an embedded derby database (bootstrapping) by running https://github.com/LinuxForHealth/FHIR/blob/main/build/derby-bootstrap.sh. For example: 
    build/derby-bootstrap.sh /path/to/wlp/usr/servers/defaultServer
    This will use the fhir-persistence-schema cli jar to create derby databases under this directory. The script creates 4 separate databases, but only "fhirDB" is used by default...the others are used by our integration tests.

Note: the fhir-server application is large and takes a bit to start; it is recommend to turn automatic publishing off. This can be done by double-clicking the server in the eclipse Servers view, expanding "Publishing" in the Overview, and selecting Never publish automatically.

At this point you should have a working server. You can start and stop the server from the Servers view. If you wish to run our integration tests (under fhir-server-test), you must configure the server as described in the next section.

Running the end-to-end tests from Eclipse

To configure the server for our end-to-end integration tests:

  1. From eclipse, copy the folders from fhir-server-webapp/src/test/liberty/config to Liberty Runtime/servers/defaultServer. After the copy you should have:
    • three folders under "defaultServer/config": default, tenant1 and tenant2
    • two files under "defaultServer/configDropins/overrides": datasource-derby.xml and trace.xml
  2. From eclipse, copy fhir-operation-test/target/fhir-operation-test-<VERSION>.jar to defaultServer/userlib/, replacing VERSION with the current version. If the server is running, you will need to re-start it.
  3. Update the entry for fhirServer.core.serverRegistryResourceProviderEnabled to true in defaultServer/config/default/fhir-server-config.json

With a running server on localhost:9443, navigate to fhir-server-test/src/test/java, right-click testng.xml, and Run As a TestNG Suite.

Alternative endpoints and client settings can be configured at fhir-server-test/src/test/resources/test.properties.

Tip: to debug tests, set fhirclient.logging.enabled = true in test.properties; this will log the exact request/response for each exchange with the server.

FHIR® is the registered trademark of HL7 and is used with the permission of HL7. Use of the FHIR trademark does not constitute endorsement of this product by HL7.

IBM and the IBM logo are trademarks of International Business Machines Corporation, registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on ibm.com/trademark.

Clone this wiki locally