Instant OpenHIE provides a framework for deploying and configuring OpenHIE components for particular OpenHIE use cases and workflows. These scripts and configurations are organised into self-contained packages. Each of these packages may depend on other packages which allows highly complex infrastructure to be setup instantly by deploying a number of packages. Instant OpenHIE itself doesn't provide any packages, it is just the framework and specification for deploying packages. Packages are implemented and maintained by the community.

Each of these packages contain scripts which setup containerised applications. The scripts configure and pre-load necessary data into the containers. Docker will be used to containerise the applications which allows them to be easily deployed.

Instant OpenHIE currently supports deploying of packages to to allow package to be easily setup both locally or on production server in a scalable and high available way.

Usage

Main Commands

Sub Commands

package

The package sub command includes commands:

The package level commands, as shown, are there to control packages within a project, as well as generate the skeleton for a new package.

Each of these sub commands accept the following flags:

E.g. ./instant package init -n interoperability-layer-openhim

For information about flags associated to any one of the package commands, do instant-linux package [command] --help

project

The project sub command includes commands:

The project level commands, as shown, are there to simultaneously perform commands on all packages in a project, as well as generate the config file for a new project, in the desired format.

Each of these sub commands accept the following flags:

For information about flags associated to any one of the project commands, do instant-linux project [command] --help

completion

The completion sub command includes commands:

The project level commands, as shown, are there to enable autocomplete for the specified shell.

A package is intended to encompass a set of functionality rather than just setup generic applications. Packages are expected to configure the applications so that they may enact a particular functional role. This may include setting up test data and pre-configuring applications.

The fundamental concept of Instant OpenHIE is that it can be extended to support additional use cases and workflows. This is achieved through packages. A package is a set of scripts and config files that are responsible for configuring a particular application, set of application or applications configured for a specific use-case. A package may depend on from another existing package for more complicated functionality.

A package is intended to encompass a set of functionality rather than just setup generic applications. Packages are expected to configure the applications so that they may enact a particular functional role with the HIE. This may include setting up test data, necessary metadata and pre-configuring applications.

Packages can be one of two different types. An infrastructural package and a use case package. Infrastructural packages setup and configure particular applications or sets of applications that may be grouped together. By themselves, these packages only start the applications and they aren't configured for a particular use case. On the other hand, use case packages rely on infrastructural packages and configure the applications set up by them and setup additional mediators that allow applications to work together. They do this to enable a particular use case to be enacted. You can think of use case packages as adding features for the end-user whereas infrastructural packages provide the dependencies to the use case packages that enable the feature to work.

Each package will contain the following types of technical artefacts:

• Bash scripts for setting up the applications required for this package’s use cases and workflows. These bash script will use docker compose files to launch container within .

• Configuration scripts to setup required configuration metadata

• Extensions to the test harness to test the added use cases with test data

The below diagram shows how packages will extend off of each other to add use cases of increasing complexity.

The fundamental concept of Instant OpenHIE is that it can be extended to support additional use cases and workflows. This is achieved through packages. Packages conform to a specific set of rules and contain scripts and resources that allow particular applications to be spun up and configured on the platforms supported by Instant OpenHIE. The currently supported platforms are local and remote deployments via Docker swarm.

Packages alone, however, do not solve the whole problem. A consistent way of managing and executing these packages is necessary. Much of the work that goes into Instant OpenHIE is developing the software that enables the packages to be deployed and managed.

Package architecture#

Packages can be one of two different types. An infrastructural package or a use case package. Infrastructural packages setup and configure particular applications or sets of applications that are commonly grouped together. By themselves these packages just get the applications started and they aren't configured for a particular use case. On the other hand, use case packages depend on infrastructural packages and configure the applications set up by them and setup additional mediators that allow these applications to work together. They do this to enable a particular use case to be enacted.

You can think of use case packages as adding features to the end-user whereas infrastructural packages provide the dependencies to the use case packages. This separation allows an infrastructural package that, say implements a FHIR server to be replaced with different packages that implements a different FHIR server. As long as these packages can be configured in a standards-based way, a use case packages could work with either of these infrastructural packages. This gives users options for the applications that they wish to use.

Each package will contain the following sorts of technical artifacts that allow it to be spun up and down within the supported platforms:

• Bash scripts for setting up the applications required for this package’s use cases and workflows. These bash script will use docker compose files to launch container within .

• Configuration scripts to setup required configuration metadata

• Extensions to the test harness to test the added use cases with test data

The exact artefacts that go into a package are described in the section on .

Execution architecture

Much of the tooling that Instant OpenHIE provides is to allow packages to be executed once they have been defined. The core principles of the execution architecture are that:

• Packages may be executed in a cross platform way (on Window, OSX or Linux)

• Complexity should be hidden from the user to make spinning up packages easy

• The software that executes the packages should be self contained so that it is easy to download and get running

The core concept of the execution architecture is that all the tooling to execute packages is contained within a single docker image - called the execution image. This enables it to run cross-platform as long as the required dependencies are installed (Docker Desktop for Windows/OSX or Docker engine and Docker compose for Linux). To enable the execution image to spin up packages using docker it is passed the docker socket file from the host so that any containers it created are in fact created on the host. The execution image gives us a consistent environment to develop for and allow us to run the scripts that execute the packages without caring about the underlying host OS, we just need to interface with the deployment platform.

An overview of the architecture is displayed below. Following that we describe how these components all works together in the sections that follow.

Go executable CLI app

The CLI app will allow the setup and configuration of Instant OpenHIE to be easily managed by the user. It is the only executable that the user would need to download to interact with instant OpenHIE. It is written in Go so that it may compile to a platform-independent executable with 0 dependencies. It will know how to fetch the execution image from docker hub and be able to execute it at the command of the user.

The app will allow the user to execute it as an interactive CLI tool, however, it will also have the ability to launch a Web UI and API server that work together to provide the user with a Web interface for managing and executing Instant OpenHIE. Choices made in the Web UI will be sent to the API server and from there the server will issue commands by running the execution image with a particular set of parameters as shown in the diagram.

The CLI app will also be responsible for ensuring the execution image is executed with the correct configuration to ensure it works cross-platform and with the necessary user setting. For example, it will mount the docker socket file into the container so that docker containers are created on the host and it will mount various user config files for docker hub and/or AWS credentials. This enables the execution image to execute as if it were configured like the user's host system.

The entry point script

The execution image, when executed itself, runs an execution script that is written in Typescript. The purpose of this script is to accept various parameters via the command line, discover the available packages and execute the requested action for a list of the available packages. The list of commandline options that it supports is shown as an example in the architecture diagram. This script is the heart of Instant OpenHIE as it is what actually executes and controls the packages. When the execution image is run this is the script that gets executed to perform all actions.

The execution image bundles all the dependencies that the execution script requires so that when the CLI app downloads the execution image from docker hub it is ready to go. The user will be required to have docker installed to run this image. The bundled dependencies in this image include: the docker and docker-compose clients and the cucumber executable for testing purposes.

It is also the responsibility of this script to determine dependencies between packages and ensure that the packages are spun up in dependency order, starting with the .

3rd party packages

By default no packages are bundled with Instant OpenHIE. Instead it is left up to the community to provide packages for application or use cases. Package location are described in the config file for the CLI app.

Jembi has create an initial set of packages that allows us to ceate a foundational HIE using the applications that we like to use, you may use this as a base to get started. See .

Test harness

A test harness is also built into the execution image that can execute a suite of tests against the stood up infrastructure and ensure that they are functioning correctly. The test harness utilizes the Gerkin language to describe tests and the Cucumber tool to execute these. Packages are required to include a Gerkin feature file and the source code that is able to execute the features in a features folder. The entry point script can then execute these test scripts on demand for each package. This provides the user with a mechanism to test an instantiation of the architecture and provides a way to explore what each use case package can do.

Instant OpenHIE is an open-source project, core developer include (v1 and v2) and (v1).

We encourage any contributions and suggestions! If you would like to get involved, please visit us on . Feel free to submit an issue or to create a PR to see your features included in the project.

Instant OpenHIE is extensible by design. Consider to support your particular use case.

We look forward to growing the set of capabilities within Instant OpenHIE together!

Instant OpenHIE aims to allow Health Information Exchange components to be packaged up, deployed, operated and scaled via a simple CLI.

Introduction

The Instant OpenHIE project aims to reduce the costs and skills required for software developers to deploy an OpenHIE architecture for quicker solution testing and as a starting point for faster production implementation and customisation.

Concepts

Instant OpenHIE provides an easy way to setup, explore and develop with the OpenHIE Architecture. It is a deployment tool that allows packages to be added that support multiple different use cases and workflows specified by OpenHIE. Each package contains scripts to stand up and configure applications that support these various workflows.

Packages

The fundamental concept of Instant OpenHIE is that it can be extended to support additional use cases and workflows. This is achieved through packages. No packages are included by default in Instant OpenHIE, packages are provided and maintained by the community.

Differences from Instant OpenHIE v1

The key changes from original Instant OpenHIE are:

• A rewrite of the original CLI - the commands and parameters have changed

• Docker swarm is now the only supported target - this allows us to scale services across servers

• A set of bash init function are included to help implementers create package deployment scripts

A package's metadata is defined in a package-metadata.json file. This file allows a package to be detected as an Instant OpenHIE package and gives key metadata that Instant OpenHIE needs.

Example

{
  "id": "dashboard-visualiser-kibana",
  "name": "Dashboard Visualiser Kibana",
  "description": "A dashboard to interpret the data from the ElasticSearch data store",
  "type": "infrastructure|use-case",
  "version": "0.0.1",
  "dependencies": ["analytics-datastore-elastic-search"],
  "environmentVariables": {
    "KIBANA_INSTANCES": 1,
    "KIBANA_USERNAME": "elastic",
    "KIBANA_PASSWORD": "dev_password_only",
    "KIBANA_SSL": "true",
    "KIBANA_MEMORY_LIMIT": "3G",
    "KIBANA_MEMORY_RESERVE": "500M"
  }
}

Instant config describes which packages to make available in the CLI and a set of profiles which allow you to easily operate on a group of packages and apply env var files to configure then.

To generate a config file use the ./instant project generate command.

A single file may be used for configuration

A reference config file looks like this:

• projectName - gives this project configuration a name

• image - defines the Docker image to use during deployment. This image should container the packages you wish to launch if you are not using customPackages. A default image with no packages included can be found at openhie/package-base:latest

• logPath - gives a location to put log of the CLI output, useful for debugging

Launching individual packages

Once a config has been defined with 1 or more packages, you may launch or stop packages by using the .

Launching a profile

If you want to launch all the packages listed in a profile with the specified configuration and env vars applied, use the .

Launching entire projects

Instead of individual packages, you can also launch everything define in your project config by using the .

Changing the default banner displayed in the CLI

The CLI banner refers to the uppermost display when running the CLI. This banner may be overwritten by including a banner.txt file at the root of the project that includes the new banner in ascii format. A tool that may be used to generate this banner may be found

Prerequisites:

• Install docker

  • On linux:

The following section explain the technical detail on how to get started with Instant OpenHIE and how to configure what you want to get deployed.

The Instant OpenHIE project aims to reduce the costs and skills required for software developers to deploy applications conforming to an OpenHIE architecture. This will enable quicker initial solution testing, demonstrations. It will also serve as a starting point for faster production implementation and customisation.

Instant OpenHIE is a simple way for semi-technical persons to install and see a complex system working against a real-world use case. It will illustrate how interoperability can work to solve health challenges. It will also show how a national interoperability architecture could be created with open-source software and standards.

Instant OpenHIE aim to provide a simple, portable way to deploy health information exchange systems to facilitate:

1. Demonstrable reference products - those that align with the OpenHIE Community's vision for low resource contexts

2. Rapid software development of mediators and point-of-service systems by making it possible to launch several applications easily so the developer can focus on their task

3. Reproducible, version-controlled infrastructure for user-contributed tests of the OpenHIE Architecture profiles, workflows, and use cases.

4. Production-ready containers and orchestratable components that are deployable in any context.

5. Extensibility so that anyone may create Instant OpenHIE packages and plug them into the existing Instant OpenHIE functionality.

To create a custom package, one can begin by running the package generate command of the CLI. The resulting output will have folder structure with files as below:

.
├── docker-compose.dev.yml
├── docker-compose.yml
├── package-metadata.json
└── swarm.sh

See the following section for more details on how each of these files can be used.

Packages can be added in tow different ways. These are described below.

Using a custom package config

You may define custom packages either in the config file or via a command line flag. This configuration can either be a local path to the package or a github url.

In a custom docker image

Packages can be built into a custom docker image that you may version and push to Docker Hub as you wish. This is the image referenced in the image property of the config file. This image MUST be built by extending the openhie/package-base package which contains some key dependencies. See an example of how Jembi does this . You simple need to add your package folder into the image.

A swarm.sh file acts as an entry point to your package and runs within the instant container during deploy.

Two arguments are passed by default into the swarm script - $1 is the action type ( init|up|down|destroy ) - $2 is the MODE in which it is run (dev)

Due to this script running in the instant container, all references made to files within the package folder would need to be prefixed with the PACKAGE_PATH variable

To supply config option to your package, make use of env vars which will be made available to this script and therefore to any docker command that you execute (so you may use env vars in your compose files for example). There are various options on the CLI via flags or the config file to supply env var files or env vars themselves.