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:
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.
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:
The openhim_core_transaction_api_url is displayed in the output when starting up Instant OpenHIE
Accessing the services created by this package:
- Console: Displayed in the output during startup
- Username: email@example.com
- Password: instant101
- HAPI FHIR
- This service should not be publicly accessible and only accessed via the Interoperability Layer
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:
docker-compose.ymlfile - sets up the base applications
docker-compose.config.ymlfile - configures the OpenHIM with a channel route to HAPI FHIR
docker-compose.dev.ymlfile - 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.
- Docker Compose
Before proceeding, ensure that you are in the directory (
core/docker/) containing the
From the working directory, execute our
This will create all the services and print out their logs in the terminal.
#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-composefile to be executed. Omitting this flag will look for the default
--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.
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-composescript to create the services
docker-composescript to override some of the default configurations.
Development environment only as this exposes service ports.
Can specify three
Should use only two
If you are working with multiple cluster hosting clients you may need to switch cluster context for your deployment. See the below commands:
For the Kubernetes deployment to work as expected, we need to ensure we have
minikube installed on our local machine running the deployment.
Follow these steps to install minikube
Once installed, we can start the minikube service by executing the below command:
This also updates the VM settings to make use of 4 CPU's and 8GB of RAM, instead of the default 2 CPU's and 4GB of RAM
Before we proceed with creating our
Core Package services, we need to ensure we are in the correct directory containing our bash setup scripts.
Once you are in the correct working directory (
core/kubernetes) we can proceed to create our core Instant OpenHIE deployment with the following command:
The OpenHIM console url will be displayed in the terminal output when the script completes. The Url may take a few minutes to become active as the pod may not be fully initialized yet.
This bash script will apply the kubernetes
kustomization.yaml file which controls the
Core Package components (i.e. OpenHIM and HAPI-FHIR).
On first run, the setup may take up to 10 minutes as the Docker images for each component will need to be pulled. This won't happen on future runs.
#View running Kubernetes resources
Execute the below commands to see the running Kubernetes resources and the state that they are in.
To display all resource: (Some new resources are not listed here)
To tear down this deployment, use the opposing command:
To completely remove all project components, use the following option:
#Initial OpenHIM Config
We have included a useful set of scripts to initialize the OpenHIM and set it up to communicate with the HAPI-FHIR server.
This will change the default user's password of the OpenHIM to
instant101, and create a channel configured to route traffic to the HAPI-FHIR instance.
kubernetes directory, use the following command to implement:
These scripts can be duplicated and modified to implement custom imports
To clean up the remaining job and pods from a successful setup, run the following:
Once the config is done HAPI FHIR will be accessible on: https://OPENHIM_CORE_HOSTNAME/fhir/
You can test that the OpenHIM is routing requests to HAPI FHIR by running:
#Development mode for exposed services
To run in development mode, run the following command:
In this mode the OpenHIM mongo database, HAPI FHIR server, and the MySQL database can be accessed directly from their urls.