streamline-emr/README.md

Streamline EMR

Packaging and installation tools for Streamline's "Streamline EMR" application.

Setup

1. login to the gitlab docker registry: docker login registry.gitlab.com
2. update submodules: git submodule update --init

Building

To build, simply run ./package to generate a new application package.

The package script will assign a few variables by default, specifically:

CONFIG=${CONFIG:-${LOCATION}/config.json}
COMPOSE=${COMPOSE:-${LOCATION}/docker-compose.yml}
BUILD_DIR=${BUILD_DIR:-${LOCATION}/build-packages}

If necessary, each of these may be overridden by running with VAR=VALUE ./package.

The hosted-app-utils project provides additional customization via command line arguments. This can be used to modify the package name, skip packaging of images, build for only one platform and more. For a list of options, run ./package -h.

Installing

1. extract the generated archive file in a temporary folder on the target system
2. run <package-name>/install.sh
3. (optional) configure an app.conf file for integration with Signalytic services (e.g. dbsync)

Running

Production (systemd)

On a production system, systemd will manage the lifecycle of the application, e.g.

# enable and start the the application service
systemctl daemon-reload
systemctl enable streamline-emr
systemctl start streamline-emr

# stop the application service
systemctl stop streamline-emr

# restart the application service
systemctl restart streamline-emr

Docker

In a docker environment, the application must be started manually. This is done by running the start script, for example:

/var/signalytic/clientapps/streamline/streamline-emr/start

Similarly, to stop the application:

/var/signalytic/clientapps/streamline/streamline-emr/stop

Manual

During development or initial setup, it may be convenient to manually control the application. Note that manually managing the application requires that the systemd service be disabled:

# check status
systemctl status streamline-emr

# stop service
systemctl stop streamline-emr

From here, the same start and stop scripts used during docker development can be used to manage the application.

Monitoring

The script monitor can be used at any time to query the current status and usage of the application. Two queries are made:

• service status: current status of each docker service including health, up-time, etc.
• resource usage: reporting on cpu, memory, disk, and network usage for each container

If the bgsystemlog program is found, data will be written to the Signalytic system log under the streamline_emr_status and streamline_emr_usage locations using json format.

Configuration

Certain configuration options can be adjusted by setting environment variables or by defining these variables in a .env file stored in the same directory as the docker-compose.yml file. A template file template.env provides an example with all values set to their defaults.

Important note when using "sibling containers": the sibling container method uses the host docker socket to provide containers with access to docker. As a result, port mappings and volume mount points all refer to the host system rather than the container from which the docker command originates.

App Configuration

An app.conf file is required for integration with other Signalytic services. A template is provided which demonstrates integration with the dbsync service. Note that all empty fields must be assigned values before use.

Implementation Notes

Scripts

Several scripts are used to manage app instances, including: start: main entry point - calls either setup or docker compose up -d setup: run once - loads default data for the facility and applies initial database configuration then starts the application stop: stops the application autoheal: managed by start and stop scripts, checks for and restarts any services that become unhealthy monitor: checks the status of each instance service and sends data to bgsystemlog if installed

Docker Images

We want to use our own copy of the Docker images hosted on our GitLab Registry. The docker folder contains a set of Dockerfiles that should be used for generating images.

If not already configured, ensure appropriate docker credentials are available:

# Login to the GitLab registry (Signalytic packages)
docker login registry.gitlab.com

# Login to an external Docker Hub registry
docker login -u <user> -p <credentials>

The script docker/build-image can be used to automatically build, tag, and push images with standard naming conventions. To build and push all images, simple run build-image -p. To simply build images and skip pushing to a registry, omit the -p flag.

Building for another platform (e.g. building arm64 from amd64 host) may fail if the Dockerfile requires running certain commands. To build only specific images, dockerfiles may be specified with build-image -f <DOCKERFILE> [ -f <DOCKERFILE> ... ]

Other options can be specified to override the image name or version. See the help menu for full details: build-image -h

Conventions

• We are building for two platforms: linux/amd64 (x86_64) and linux/arm64 (aarch64)
• One images is currently required: streamline-emr
• Images will be stored to GitLab with the name: registry.gitlab.com/signalytic/client-external/streamline/streamline-emr/<image>/<arch>:<tag>
  • example: registry.gitlab.com/signalytic/client-external/streamline/streamline-emr/streamline-emr/arm64:latest