Deploy a Healthcare Action Engine Container Stack

Step 1: Download and Extract the HealthShare Sample Container Deployment

You must make several files available in order for an operational Healthcare Action Engine container stack to deploy successfully. To help you get started, InterSystems® provides a GitHub repository which contains examples of these files, including a sample working directory which you can use as a template for your deployment.

Subsequent instructions on this page reference the contents of this repository. Before proceeding, download the HealthShare Sample Container Deployment repository here: https://github.com/intersystems/healthshare-sample-container-deployOpens in a new tab. Then, extract the contents of the repository on your host system or in external cloud storage.

Step 2: Set Up the Working Directory Structure on the Host

However you organize the files which support your container deployment on the host, you must specify those file locations in the environment file and the docker-compose up command. For simplicity, the sample repository provides a compact template of a working directory; the relevant variables in this template working directory’s environment file are already configured so that they match the template working directory’s structure.

The working directory is named sample_deploy in both the sample repository and the directory tree image which follows. Elsewhere, the documentation refers to this directory as <working-dir>.

In this template, the working directory contains two files and three subdirectories which contain additional files:

Step 3: Create the Base Configuration JSON File

When an InterSystems product is deployed from a kit, many details about how the instance operates (such as the namespace or network configuration) are specified after the kit has been installed. However, this is impractical for a container deployment.

The base configuration file uses JSON notation to describe how the instance container should be configured at deployment time. The file consists of three parts:

• A feature configuration for the namespace, which initializes a namespace on the instance.

• A network configuration for the instance, which specifies network and secure communication details for the instance.

• An OAuth configuration for the instance, which configures the instance to authorize itself as part of a HealthShare federation using the federation’s OAuth 2.0 server. Because HAE is a stand-alone solution, you should leave this part of the base configuration empty.

The sample repository contains several files to help you create a base configuration file for your Healthcare Action Engine container stack:

• A skeleton hs-base-config.json fileOpens in a new tab, which models the structure of a complete base configuration file. It includes empty feature, network and OAuth sections.

• A sample feature configurationOpens in a new tab for the Healthcare Action Engine namespace.

• A sample network configurationOpens in a new tab.

Using the sample files and the instructions which follow, construct a complete base configuration file for your instance container. Then, place your base configuration file (named hs-base-config.json by default) in your <durable-hs-config> directory.

Feature Configuration

At minimum, a feature configuration for the Healthcare Action Engine must include the information provided in the following example:

"feature-config": {  
   "name": "<MYNAME>",
   "type": "HealthcareActionEngine",
   "template": "HSEDS.Sample.Production",
   "disabled": false,
},

Where <MYNAME> is the name you choose for your Healthcare Action Engine namespace—for example, HAE. Note that the value of <MYNAME> must be uppercase.

Network Configuration

Specify details about your instance’s network communication within the network configuration, as in the following example:

"network-config": {
   "networkHostName": "myhost.ixrinternal.com",
   "securePort": 8443,
   "secureIsActive": true,
   "secureWebServerPrefix": "",
   "tlsConfig": "HS.Secure.Demo"
}

The tlsConfig parameter creates an empty SSL/TLS configuration. To populate the SSL/TLS configuration with certificate information and other configuration details, use a configuration merge file or edit it manually after the container has been deployed.

Complete hs-base-config.json Example

The following example hs-base-config.json deploys an instance of HAE with a TLS configuration called HS.Secure.Demo.

{
    "network-config": {
        "networkHostName": "myhost.ixrinternal.com",
        "securePort": 8443,
        "secureIsActive": true,  
        "tlsConfig": "HS.Secure.Demo"
    },
    "feature-config": {  
        "name": "HAE",
        "type": "HealthcareActionEngine",
        "template": "HSEDS.Sample.Production", 
        "disabled": false,
    },
    "oauth-config": {
    }
}

Step 4: Modify the Environment File

The environment file allows you to set environment variables. The Docker Compose file refers to these variables to define parameters which govern how the HAE instance container and Web Gateway container will be deployed.

The environment variables in the list which follows must have values; other environment variables mentioned in the sample repository’s environment file are optional.

HS_IMAGE_PATH

The path to your Healthcare Action Engine image. You can obtain this from the Name property of your instance image. The value should resemble the following:

containers.intersystems.com/intersystems/healthshare_healthcareactionengine

HS_IMAGE_VERSION

The version number of your Healthcare Action Engine image. You can obtain this from the Tag property of your instance image. The value should resemble the following:

2023.2

WEBGATEWAY_IMAGE_PATH

The path to your Web Gateway image. For example:

containers.intersystems.com/intersystems/webgateway

or

containers.intersystems.com/intersystems/webgateway-arm64

WEBGATEWAY_IMAGE_VERSION

The version of your Web Gateway image. Always use the latest Web Gateway image:

latest-cd

Step 5: Modify the Docker Compose File if Needed

In most cases, you can deploy a Healthcare Action Engine container stack using the sample repository’s standard, parameterized Docker Compose file. This default Docker Compose file uses environment variable values from your environment file to deploy the Web Gateway and Healthcare Action Engine instance containers as “services.” This file also specifies default values for some parameters, in case optional environment variables are left undefined.

You can add entries to the to suit your needs—for example, to specify additional volumes. You would also have to modify the default docker compose in order to change the default paths or filenames for the Web Gateway certificates and configuration files.

Step 6: Create Custom Instance Configuration Files as Needed

The <durable-iris-config> directory on your host should contain the following files:

• iris.key — The license file for your Healthcare Action Engine instance. Note that license keys for containers are different than those used for kits; consult with an InterSystems representative to acquire the license appropriate for your deployment.

• merge.cpf — The configuration merge file, where you can specify additional configuration parameters for your Healthcare Action Engine instance. Example uses of a configuration merge file in container deployment include:

  • specifying alternate values for the HS_Services username and password (which is used by the asynchronous Events Feeder).

  • configuring instance memory settings.

  • including the certificate details for the SSL/TLS configuration that you specified using the tlsConfig property in your base configuration file’s network configuration section.

  The example merge.cpf which follows configures the “MyTestConfig” SSL/TLS configuration to use a certificate and private key that are located in <durable-iris-config>, which (in this example) mounts to/config/iris/ within the container.

  [Actions]
  
  ModifySSLConfigs:Name=MyTestConfig,CertificateFile=/config/iris/ssl-cert.pem,PrivateKeyFile=/config/iris/ssl-cert.key
  
  

  
  Note:

  Alternatively, you can manually edit the SSL/TLS configuration to add your certificate information once your instance container has been deployed.

The Web Gateway configuration directory (<working-dir>/web-gateway/ by default) should contain:

• ./certificate/ — A subdirectory where you should place your ssl-crt.key and ssl-cert.pem files in order to configure the Web Gateway to support SSL/TLS. If you are using the sample repository’s template working directory and you want to specify different names or paths for your certificate files, you must edit the provided Docker Compose file to use different names or paths for your certificate files, as there is no environment variable available.

• csp.ini — A configuration file for the Web Gateway container. A sample fileOpens in a new tab is available from the sample repository. If you are using the sample repository’s template working directory and you want to specify a different path for the csp.ini file, you must edit the provided Docker Compose file, as there is no environment variable available.

  Important:

  The Ip-Address value specified in the [REMOTE] section of the csp.ini file must match the INSTANCE_NETWORK_IP value in the environment file (or the default in the provided Docker Compose file). The default value in the provided Docker Compose file is 192.168.10.11. Unless you deploy more than one container stack on a particular host, this default value can typically be used.

• csp.conf — A configuration file for the Apache httpd web server which runs within the Web Gateway container. A sample fileOpens in a new tab is available from the sample repository. If you are using the sample repository’s template working directory and you want to use a different file path for the csp.conf file, you must edit the provided Docker Compose file, as there is no environment variable available. do not edit the supplied csp.conf file unless you have expertise with Apache httpd.

  Note:

  In the current version of the Healthcare Action Engine, the only supported web server for container deployments is Apache httpd.

Step 7: Run the Docker Compose up Command

In the working directory where your Healthcare Action Engine container stack’s docker-compose.yml file resides, run the command:

docker compose --env-file <envFile> up

Where <envFile> is the relative path to your environment file. If your Docker Compose file is not named docker-compose.yml or is in another location, use the -f flag to identify the docker compose file.

For example:

docker compose --env-file ./hae.container.env up -d

Because two services are defined in the docker-compose.yml, the docker compose command will deploy both the Web Gateway container and the HAE instance container.