Prerequisites:

• Install docker

  • On linux: install the docker package

  • On OSX or Windows: Install docker desktop

• Enable swarm mode in docker: docker swarm init

To get started with Instant OpenHIE you will first need to download the CLI tool. The binary may be download via the terminal with the following url based on your operating system

sudo curl -L https://github.com/openhie/instant-v2/releases/latest/download/instant-linux -o /usr/local/bin/instant

sudo chmod +x /usr/local/bin/instant

sudo curl -L https://github.com/openhie/instant-v2/releases/latest/download/instant-macos -o /usr/local/bin/instant

sudo chmod +x /usr/local/bin/instant

docker context use default

To test that the binary works, run the executable with no commands to see the help text.

$ instant
A cli to assist with package deployment and management

Usage:
  cli [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  package     Package level commands
  project     Project level commands
  version     Print the CLI version

Flags:
  -h, --help   help for cli

Use "cli [command] --help" for more information about a command.

Next, you would want to configure which packages Instant can deploy for your particular needs.

Instant doesn't ship with any default packages to deploy. Packages are expected to be created by the community and in time there will be many option available. Jembi has curated a set of packages that we commonly use to help implementer to get started with a foundational set of health information exchange components. To get started with that pre-configured package set, see the OpenHIM Platform docs.

Otherwise, you may create your own config for your own set of packages. Continue to config section to find out how.

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 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.

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.

As a coding standard we encourage use of the Shell Style Guide

Should you use VS Code for editing we suggest the pinage404.bash-extension-pack

Example

#!/bin/bash

readonly ACTION=$1
readonly MODE=$2

PACKAGE_PATH=$(
  cd "$(dirname "${BASH_SOURCE[0]}")" || exit
  pwd -P
)
readonly PACKAGE_PATH

main() {
  if [[ "${MODE}" == "dev" ]]; then
    echo "Running Dashboard Visualiser Kibana package in DEV mode"
    kibana_dev_compose_param="-c ${PACKAGE_PATH}/docker-compose.dev.yml"
  else
    echo "Running Dashboard Visualiser Kibana package in PROD mode"
    kibana_dev_compose_param=""
  fi

  if [[ "${ACTION}" == "init" ]] || [[ "${ACTION}" == "up" ]]; then
    docker stack deploy -c "${PACKAGE_PATH}"/docker-compose.yml $kibana_dev_compose_param instant
  elif [[ "${ACTION}" == "down" ]]; then
    docker service scale instant_dashboard-visualiser-kibana=0
  elif [[ "${ACTION}" == "destroy" ]]; then
    docker service remove instant_dashboard-visualiser-kibana
  else
    echo "Valid options are: init, up, down, or destroy"
  fi
}

main "$@"

Breakdown

• Lines 2 & 3 extract the two arguments that instant provides to this script during any deploy command involving this package ie. the ACTION and MODE respectively.

• Lines 6-9 retrieve the current path to this swarm.sh file which should exist at the root of your package. This path may then be used to reference any files within the package eg. docker-compose.yml.

• Lines 12-32 define and execute a main block within which all our executable code will run. This is done to preserve the scope of any locally scoped variables used in the script.

• Lines 13-19 specify the path to a docker-compose file that contains override configs specifically for dev use. This variable then gets used on line 22 to override the default configs of the main docker-compose file.

• Lines 21-29 define logic based on the ACTION parameter

• Line 22 deploys all services specified in the docker compose files provided and assign them to the instant stack. The dev docker compose file is only used if the MODE argument was received as "dev".

• Line 24 scales down the specified services to 0. This stops all containers but keeps their volumes and configs intact which will allow you to perform maintenance without losing data.

• Line 26 removes the service which will also stop and remove any of it's containers. Volume removal may also occur here

Utility functions

A number of bash utility functions are also provided for more complex tasks relating to docker or common tasks that are made simpler. Please see the utils folder in the source code for a list of all available utility functions.

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: platform
image: jembi/platform
logPath: /tmp/logs

packages:
    - <<package-id>>

customPackages:
    - id: <<custom-package-id>>
      path: <<custom-package-path>>

profiles:
    - name: <<profile-name>>
      packages:
        - <<profile-package-id-1>>
        - <<profile-package-id-2>>
      envFiles:
        - <<env-file-1>>
        - <<env-file-2>>
      dev: false
      only: false

• 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

• packages - lists the package ids that you expect to exist in the image

• customPackages - lists packages that are not in the image. The path can either point to a file system location or a github url.

• profiles - lists a number of profiles that are defind for this project. A profile is a group of packages, config and env var files that can be operated on (i.e. launched) together.

  • name - a profile name

  • packages - list of package ids that form part of this profile

  • envFiles - a lsit of env var file to apply when operating on these packages to configure then to do what you want

  • dev - launches the profile is dev mode, which is an instruction to packages to start in dev mode which usually mean to expose more ports than they usually would for development and debugging reasons

  • only - instructs the profile to operate on only the packages listed and any package dependencies will be ignored.

Launching individual packages

Once a config has been defined with 1 or more packages, you may launch or stop packages by using the ./instant package <init|up|down|remove> -n <package_id> command.

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 ./instant package <init|up|down|remove> -p <profile_name> command.

Launching entire projects

Instead of individual packages, you can also launch everything define in your project config by using the ./instant project <init|up|down|remove> command.

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 here

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.

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

• The entry point bash script for packages is now named swarm.sh

• The instant.json file is now renamed to package-metadata.json

• No packages are included by default, these are left up to the community to provide and maintain. Instant OpenHIE simply becomes the packaging specification and deployment tool.

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.

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 for Jembi Platform here. You simple need to add your package folder into the image.

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

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 Docker Swarm.

• 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 creating packages.

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 Core package.

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 OpenHIM Platform.

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 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 Docker Swarm to allow package to be easily setup both locally or on production server in a scalable and high available way.

Instant OpenHIE is an open-source project, core developer include Jembi Health Systems (v1 and v2) and IntraHealth International (v1).

We encourage any contributions and suggestions! If you would like to get involved, please visit us on Github. 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 creating a package to support your particular use case.

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