# 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:
```bash
# 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`