From d60c85fa143506bccfe2be2e784e551a9856b76e Mon Sep 17 00:00:00 2001 From: Alec Turner Date: Mon, 28 Oct 2024 15:10:50 -0700 Subject: [PATCH] updated readme to match latest usage --- README.md | 131 +++++++++++++++++++----------------------------------- 1 file changed, 45 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 587ed3fe..8768a054 100644 --- a/README.md +++ b/README.md @@ -1,96 +1,13 @@ # Streamline EMR -Packaging and installation tools for Streamline's "Streamline EMR" application. +Packaging and installation tools for the Streamline EMR web app. ## Setup 1. login to the gitlab docker registry: `docker login registry.gitlab.com` -2. update submodules: `git submodule update --init` +2. update submodules: `git submodule update --init --recursive` -## 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 `/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 +## 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: @@ -113,3 +30,45 @@ Other options can be specified to override the image name or version. See the he - 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//:` - example: `registry.gitlab.com/signalytic/client-external/streamline/streamline-emr/streamline-emr/arm64:latest` + +## 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} +SRC=${SRC:-${LOCATION}/src} +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`. + +Helpful options during development: +- `--no-compression`: skip image compression to speed up packaging (packages will be much larger) +- `--app`: skip packaging of images altogether + +## Installing +### Automated (Filetransfer) +1. Copy package to the management node (e.g. `scp build-packages/ @:`) +2. SSH into the management node and become root (e.g. `ssh @`, `sudo su`) +3. (optional) Prepare a filetransfer channel (e.g. `mkdir -p /var/signalytic/filetransfer/-`) +4. Prepare a filetransfer update: +```bash +mkdir -p tmp/ +mv tmp// +openssl sha256 -binary tmp// | base64 - > tmp//_hash_ +``` +5. Copy the filetransfer update to the appropriate channel (e.g. `mv tmp/1 /var/signalytic/filetransfer/-/`) +6. (optional) Restart filetransfer: `systemctl restart filetransfer` +7. If necessary, add the package to the target nodes' selective sync lists +``` +bgkvs --cred admin: -B _conf -N _shared_ -d -k filetransfer.selective_sync_packages.[0= +bgkvs --cred admin: -B _conf -N _shared_ -d -k filetransfer.selective_sync_packages.[1= +bgkvs --cred admin: -B _conf -N _shared_ -d -k filetransfer.selective_sync_packages.[2= +``` + +### Manual +1. extract the generated archive file in a temporary folder on the target system +2. run `/install.sh`