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
Download the binary
Grant the binary executable permissions
Download the binary
Grant the binary executable permissions
Ensure docker desktop is using the default context else Instant won't be able to run docker containers
For Windows it is recommend to install the WSL tools and install an Ubuntu vm. From there continue to follow the linux instructions. Ensure that you have Docker Desktop support enabled for your WSL instance.
To test that the binary works, run the executable with no commands to see the help text.
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.
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
The config.yml file should be located at the root of the project, or pointed to using the --config-file command
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
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.
Packages listed in a profile must be specified in either the customPackages or packages section
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.
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.
Instead of individual packages, you can also launch everything define in your project config by using the ./instant project <init|up|down|remove> command.
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.
The CLI is supported for Linux and MacOS
The CLI must be named 'instant-linux' for Linux, and 'instant-macos' for MacOS for autocomplete to work
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
After generating a new package, remember to add the package ID to the config file
Packages in a project can only be started if included in the config file
Command line arguments like --dev and --only will overwrite those specified in the config file profiles when using that particular profile
Env vars in --profile env var files are appended to by env var files specified in the command line, or overwritten by the command line env var files if there are conflicting env vars
Custom packages in a profile must be specified in the customPackages section of the config file
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
The completion sub command includes commands:
The project level commands, as shown, are there to enable autocomplete for the specified shell.
Remember to reload your shell after generating the autocomplete script