How to setup Instant OpenHIE on any platform using the GO CLI
info
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.
Overview#
The purpose of this how-to guide is to help set up a complete development environment for Instant OpenHIE on any platform using the GO CLI tool.
The GO CLI tool is a tool built for getting instant OpenHIE up and running through an easy to use interactive CLI and a non-interactive CLI for the more technical users.
Prerequisites#
System requirements:
- Stable internet connection with high download speeds.
- 16GB RAM.
- At least 20GB free space.
- Docker for your specific platform
1. Download the GO CLI for your chosen platform#
The latest version of the GO CLI will be available at our GitHub releases page under the assets section. From the list, choose the specific file that's applicable to your operating system (platform) and download it.
Note: MacOS currently blocks the CLI from executing due to a unknown developer issue, this is being worked on.
Note: Step 2 below will outline running the CLI in the interactive mode, skip to step 3 below for the non-interactive mode.
2. Run the CLI in interactive mode#
2.1 Open your favourite terminal and run the executable file (linux and macOS)#
e.g. using an absolute path to the file:
or using a relative path to the file:
Note: in Windows one can simply double click the file, but it will work in Powershell as well.
Currently the file downloaded from Github will not have the correct file permissions on linux and macOS, we are working on this, but in the meantime, you can execute the following command to update the file permissions to be executable:
For Linux:
For MacOS (currently not supported)
2.2 Follow the prompts#
Use Docker on your PC: This will open up the menu for docker installation options
Use a Kubernetes Cluster: This will notify the user that the Kubernetes install options is not currently implemented.
Install FHIR package: This can be used to install remote FHIR packages.
Default Install Options Prompt:#
Default Install prompt details:#
- Initialise All Packages: This will initialise all default packages that are built into instant.
- Initialise Core: This will initialise the core package and its dependencies.
- Initialise Client: This will initialise the client package and its dependencies.
- Initialise Elastic-Analytics: This will initialise the elastic-analytics package and its dependencies.
- Initialise Elastic-Pipeline: This will initialise the elastic-pipeline package and its dependencies.
- Initialise Electronic Medical Record: This will initialise the electronic medical record package and its dependencies.
- Initialise Health Management Information System: This will initialise the health management information system package and its dependencies.
- Initialise Health Worker: This will initialise the health worker package and its dependencies.
- Initialise Facility Registry: This will initialise the facility registry package and its dependencies.
- Initialise Workforce: This will initialise the workforce package and its dependencies.
- Stop All Services and Cleanup Docker: This will stop and remove all packages that are currently deployed.
- Stop and Cleanup Core: This will stop and remove the core package and its dependencies.
- Stop and Cleanup Client: This will stop and remove the client package and its dependencies.
- Stop and Cleanup Elastic-Analytics: This will stop and remove the elastic-analytics package and its dependencies.
- Stop and Cleanup Elastic-Pipeline: This will stop and remove the elastic-pipeline package and its dependencies.
- Stop and Cleanup Electronic Medical Record: This will stop and remove the electronic medical record package and its dependencies.
- Stop and Cleanup Health Management Information System: This will stop and remove the health management information system package and its dependencies.
- Stop and Cleanup Health Worker: This will stop and remove the health worker package and its dependencies.
- Stop and Cleanup Facility Registry: This will stop and remove the facility registry package and its dependencies.
- Stop and Cleanup Workforce: This will stop and remove the workforce package and its dependencies.
Custom Install Options Prompt:#
Custom Install prompt details:#
- Choose deploy action (default is init): Choose which deploy action to execute.
- Specify deploy packages: Specify the package IDs that you want to operate on as part of the installation.
- Specify environment variable file location: Specify a filepath to an environment variables file.
- Specify environment variables: Specify a comma delimited list of environment variables that should be aplied to the instant OpenHIE docker container.
- Specify custom package locations: Specify a comma delimited list of paths (filepaths or URLs) to custom packages.
- Toggle only flag: This will toggle the only flag between an on and off state to enable isolation of the deploy action to only operate on specific packages.
- Specify Instant Version: Specify which release version of instant OpenHIE to use.
- Execute with current options: Run the docker command to create and start up the instant OpenHIE docker container to install the rest of the services based on the custom options selected.
- View current options set: Print out the current selected options to the CLI.
- Reset to default options: Reset the current selected options to the default options to clear selection.
Back & Quit:#
These options are available at every prompt.
- Back: This option will take the user back one command so that they can make a different selection.
- Quit: This option will terminate the execution of the GO CLI as well as stopping the instant OpenHIE docker container.
3. Run the CLI in non-interactive mode#
3.1 Open your favourite terminal and run the executable file (linux and macOS)#
e.g. using an absolute path to the file:
or using a relative path to the file:
Note: in Windows it's best to run non-interactive through Powershell.
Currently the file downloaded from Github will not have the correct file permissions on linux and macOS, we are working on this, but in the meantime, you can execute the following command to update the file permissions to be executable:
For Linux:
For MacOS (currently not supported):
3.2 Explanation of all flags and custom options#
Custom Install details:#
Format:
e.g.
At least two of the following arguments is required (values in brackets are from above example):
- Target(docker): docker is the only supported option at the moment.
- Deploy action(init): init, destroy, up, down or test
- Deploy packages(core data-analytics): Specify the package IDs that you want to operate on as part of the installation.
- Specify environment variable file location(--env-file="C:\Projects\hiv-case-reporting.env"): Specify a filepath to an environment variables file.
- Specify environment variables(-e="DOMAIN_NAME=testDomain"): Specify an environment variable that should be aplied to the instant OpenHIE docker container.
- Specify custom package locations(-c="C:\Projects\packages\data-pipeline"): Specify a comma delimited list of paths (filepaths or URLs) to custom packages.
- Toggle only flag(only): This will enable isolation of the deploy action to only operate on specified packages and not take their dependency tree into consideration.
- Instant openHIE Image Version(--instant-version="latest"): Specify the version of the instant openHIE image to use.