updated readme to match latest usage

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:
+## Docker Images
-```
-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:
@@ -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/<image>/<arch>:<tag>`
   - 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/<package> <user>@<mgmt-node-url>:`)
+2. SSH into the management node and become root (e.g. `ssh <user>@<mgmt-node-url>`, `sudo su`)
+3. (optional) Prepare a filetransfer channel (e.g. `mkdir -p /var/signalytic/filetransfer/<app-name>-<arch>`)
+4. Prepare a filetransfer update:
+```bash
+mkdir -p tmp/<update-number>
+mv <package> tmp/<update-number>/
+openssl sha256 -binary tmp/<update-number>/<package> | base64 - > tmp/<update-number>/_hash_
+```
+5. Copy the filetransfer update to the appropriate channel (e.g. `mv tmp/1 /var/signalytic/filetransfer/<app-name>-<arch>/`)
+6. (optional) Restart filetransfer: `systemctl restart filetransfer`
+7. If necessary, add the package to the target nodes' selective sync lists
+```
+bgkvs --cred admin:<pass> -B _conf -N _shared_ -d <node> -k filetransfer.selective_sync_packages.[0=<pkg1>
+bgkvs --cred admin:<pass> -B _conf -N _shared_ -d <node> -k filetransfer.selective_sync_packages.[1=<pkg2>
+bgkvs --cred admin:<pass> -B _conf -N _shared_ -d <node> -k filetransfer.selective_sync_packages.[2=<pkg3>
+```
+
+### Manual
+1. extract the generated archive file in a temporary folder on the target system
+2. run `<package-name>/install.sh`