signalytic/streamline-emr
1
0
Fork 0
mirror of https://gitlab.com/signalytic/client-external/streamline/streamline-emr.git synced 2026-09-11 10:41:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Simplify application management and align with other docker applications

Browse Source 
The notion of application "instances" is dropped in favor of a simpler,
single-instance approach. Default values are provided for all configuration
variables so allow the app to run without additional manual configuration.

A health check and auto-heal script are added to automatically restart the
application in case it becomes unavailable during operation.
This commit is contained in:
alec.turner
2024-03-25 09:34:34 -07:00
parent 6c59b1ab76
commit 9cbefc841f
14 changed files with 189 additions and 211 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+53 -65
View File
@@ -12,9 +12,7 @@ Several defaults can be overridden with command line options or by setting appro
## Installing
1. extract the generated archive file in a temporary folder on the target system
2. run `<package-name>/install.sh`
3. add a `instance.conf` file at the root of the install directory (see notes below)
4. (optional) restart the systemd service if running on a system with systemd installed: `systemctl restart streamline-emr`
5. (optional) configure an `app.conf` file for integration with Signalytic services (e.g. dbsync)
3. (optional) configure an `app.conf` file for integration with Signalytic services (e.g. dbsync)
## Running
### Production (systemd)
@@ -32,85 +30,75 @@ systemctl stop streamline-emr
systemctl restart streamline-emr
```
## Monitoring
The script `monitor` can be used at any time to query the current status of all instances. If the `bgsystemlog` program is found, status data will be written to the Signalytic system log under the `streamline_emr` location (json format).
### Docker
In a docker environment, the application must be started manually. This is done by running the `entry` script, for example:
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/entry
/var/signalytic/clientapps/streamline/streamline-emr/start
```
Note that the entry script will block until the first service stops or until interrupted.
If multiple instances are run from the same machine, additional configuration may be required to differentiate the instances. This is generally the case when using the "sibling container" method for running docker from within a docker container. See the `Configuration` section for more details.
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. These variables are:
`APP_PORT`: port mapping for the web app server
`CONTAINER_NAME`: name of the application container
`DATA_DIR`: directory to be mounted for peristant data
`COMPOSE_PROJECT_NAME`: assign the project name associate with the compose file - this avoids conflicts when the "same" compose file is used to manage multiple instances (e.g. when using docker sibling containers)
`IMAGE`: optional, overrides the default `streamline-emr:2.0` image
Each instance of the app uses its own `.env` file to specify its configuration. This is automated through the `start` script using information stored in a file `instances.conf`. This file defines two lists:
`INSTANCES`: a list of unique instance names
`APP_PORTS`: a corresponding list of port numbers to map to the local host
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.
### Example Configuration Files
The following snippet shows an `instances.conf` file with 3 instances defined. Instance `test0001-_default` will use port `3001`, `test0002-_default` will use `3002`, etc.
```
INSTANCES="test0001-_default" "test0002-_default" "test0003-_default"
APP_PORTS=3001 3002 3003
```
### 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.
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.
## Scripts
## Implementation Notes
### Scripts
Several scripts are used to manage app instances, including:
`entry`: main entry script used to start all configured instances - does not return until a service stops or the process is interrupted.
`start`: loads configuration details from `instances.conf`, then configures and starts each application instance in a dedicated subfolder
`stop`: locates and stops all instances, even if no longer defined in `instances.conf`
`monitor`: checks the status of each instance service and sends data to `bgsystemlog` if possible (loc: `streamline_emr`)
## Docker Images
`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.
### Automated
The script `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.
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`
### Manual
1. Make sure you are logged in to the Signalytic GitLab Registry:
```bash
# Login to the registry
docker login registry.gitlab.com
```
2. Build an image (note: we're using platforms `linux/amd64` and `linux/arm64`)
```bash
# Build an image
docker build -f ${DOCKERFILE} --platform ${PLATFORM} -t ${IMAGE_TAG} .
```
3. Make a copy of an existing image:
```bash
# Create a tag
docker tag ${IMAGE_ID} registry.gitlab.com/signalytic/client-external/streamline/streamline-emr/${NAME}:${TAG}
```
3. Push the image to our GitLab Registry:
```bash
# Push the image
docker push registry.gitlab.com/signalytic/client-external/streamline/streamline-emr/${NAME}:${TAG}
```
#### 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`