Skip to content

Setting up for development

Jump to bottom
Lee Surprenant edited this page Jan 11, 2022 · 93 revisions

Prereqs

Java 8 (or above)

The IBM FHIR Server has been tested with OpenJDK 8, OpenJDK 11, and the IBM SDK, Java Technology Edition, Version 8. To install Java on your system, we recommend downloading and installing Java 11 OpenJ9 from https://adoptopenjdk.net.

Maven

The IBM 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 IBM FHIR Server in a docker container or build the docker image. It's recommended you install Docker Desktop.

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 Style Guide Style Guide, remember to import the formatting. Click Eclipse > Preference. Click on Java > Code Style > Formatter. Import the Style Guide - TeamRules.xml 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 IBM FHIR Server repository following the GitHub Standard Fork & Pull Request Workflow. For instance, git clone [email protected]:<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 IBM FHIR Server 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 IBM FHIR Server from Maven.

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

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

Note: currently, there are some benign ArrayIndexOutOfBoundsExceptions while starting from the liberty maven plugin...this will be investigated under https://github.com/IBM/FHIR/issues/3092 but the server should still come up fine.

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 IBM 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.
  1. 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 IBM 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 "fhir-server".
  2. Once done installing, navigate to <targetDir>/wlp/usr/servers/fhir-server/apps and delete the apps (rm -f *.war) contained in that directory. We're going to replace them with the apps from Eclipse.
  3. 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.
  4. From eclipse, copy the folders tenant1 and tenant2 from fhir-server/liberty-config-tenants to Liberty Runtime/servers/fhir-server/config. After the copy you should have three folders there: default, tenant1 and tenant2. (if the server is running, you will need to stop and re-start it)
  5. From eclipse, copy fhir-operation-test/target/fhir-operation-test-<VERSION>-tests.jar to Liberty Runtime/servers/fhir-server/userlib/, replacing VERSION with the current version. If the server is running, you will need to stop and re-start it.
  6. 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.
  7. 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 67.
  8. From Eclipse, navigate to your Liberty server > configDropins > disabled, copy the database-derby.xml into the defaults directory.
  9. Create the derby databases (bootstrapping) by running https://github.com/IBM/FHIR/blob/main/build/derby-bootstrap.sh. For example: 
    build/derby-bootstrap.sh ~/path/to/wlp/usr/servers/fhir-server
    This will use the fhir-persistence-schema cli jar to create derby databases under this directory which align with the locations in the database-derby.xml copied in the previous step.

Running the server

Once configured, you can start and stop the server from the Servers view.

Running the end-to-end tests from Eclipse

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.

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