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

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

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 or via a . 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.

As a coding standard we encourage use of the

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

Example

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

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.