Skip to main content

Core Package

info

The Instant OpenHIE architecture, codebase, and documentation are under active development and are subject to change. While we encourage adoption and extension of the Instant OpenHIE framework, we do not consider this ready for production use at this stage.

The Instant OpenHIE Core Package is the common base of the Instant OpenHIE system and it provides fundamental components that other packages may build off of.

This package consists of two components that support all other packages, these are:

Package functionality#

This package sets up containers that support the OpenHIM as well as the HAPI FHIR server. It also configures the OpenHIM with a HAPI FHIR channel. This allows authorised data transfer to the HAPI FHIR server through the OpenHIM.

An example of what the core package includes, as well as how a sample package (in this case the Health-Workforce package) may use the services the core package provides, is shown below.

Package architecture

To use the HAPI FHIR server from an external point of care application, you can access it through the OpenHIM at a URL like the following:

curl <openhim_core_transaction_api_url>/fhir/Patient

The openhim_core_transaction_api_url is displayed in the output when starting up Instant OpenHIE

Accessing the services created by this package:

  • OpenHIM
    • Console: Displayed in the output during startup
    • Username: root@openhim.org
    • Password: instant101
  • HAPI FHIR
    • This service should not be publicly accessible and only accessed via the Interoperability Layer

Deployment strategy#

The OpenHIM was already dockerised so we were able to re-use those images for our work in the core package. HAPI FHIR didn't have official dockerfiles available, however, several community contributed options existed. We chose to use what seemed like the most robust option.

We supplied Docker Compose files for the setup and configuration of these applications. We chose to split the docker-compose.*.yml files into three concerns:

  1. Main docker-compose.yml file - sets up the base applications
  2. Config docker-compose.config.yml file - configures the OpenHIM with a channel route to HAPI FHIR
  3. Dev docker-compose.dev.yml file - exposes all open port to the host for easy debugging. This should not be used a production environment

For Kubernetes, we created deployment and service resource files for each component of each application. The setup is orchestrated by a kustomization.yml file for easy deployment. To import configuration into the OpenHIM, we use job resources that only execute when the OpenHIM core is up. This is done with an init container which waits for the OpenHIM core port to become available.

For importing config, we use a custom image which is just a node.js container that can run node.js scripts that we define. It also has a wait-on module installed to allow it to wait on certain ports being available before executing.

Core Package Dev guide#

For testing purposes, this package can be run independently. Below are some notes of how to do this. The recommended way to run Instant OpenHIE is described here.

Select a deployment target below and follow the getting started steps in setting up this package.

Before proceeding, ensure that you are in the directory (core/docker/) containing the docker-compose script.

From the working directory, execute our docker-compose script. This will create all the services and print out their logs in the terminal.

docker-compose up

Useful compose flags#

Some additional flags can be passed to the docker-compose command making it easier to work with.

  • -d: Run the services in a detached mode. This means that when you close or exit your terminal, the services will still be running in the background.
  • -f: Specify the location of the docker-compose file to be executed. Omitting this flag will look for the default docker-compose.yml file.
  • --force-recreate: This will force the container/image to be re-created if a newer version is found. This is useful when a new image has been released but not yet pulled onto the host machine.
docker-compose up -d --force-recreate

Environment configuration#

The default script might not suit the type of environment you want to run. Therefore there are additional docker-compose files available for fine-tuning environment configuration.

  • docker-compose.yml: Main docker-compose script to create the services

  • docker-compose.dev.yml: Development docker-compose script to override some of the default configurations.

    Development environment only as this exposes service ports.

Development configuration#

Can specify three docker-compose files.

docker-compose -f docker-compose.yml -f docker-compose.dev.yml -f docker-compose.config.yml up -d
Production-like configuration#

Should use only two docker-compose files.

docker-compose -f docker-compose.yml -f docker-compose.config.yml up -d