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` diff --git a/config.json b/config.json index d06c4379..dce1b20a 100644 --- a/config.json +++ b/config.json @@ -1,7 +1,7 @@ { "name": "streamline-emr", "org": "streamline", - "version": "0.1", + "version": "1.0", "platforms": [ "linux/arm64", "linux/amd64" diff --git a/hosted-app-utils b/hosted-app-utils index 6f1a9493..3785af30 160000 --- a/hosted-app-utils +++ b/hosted-app-utils @@ -1 +1 @@ -Subproject commit 6f1a9493c1bdce87a76db53c9d0f9879c5266030 +Subproject commit 3785af3094b2b92f6daceb670e7bbb7a5d83d369 diff --git a/package b/package index e4c54743..bbde6d42 100755 --- a/package +++ b/package @@ -3,7 +3,7 @@ LOCATION="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null 2>&1 && pwd )" CONFIG=${CONFIG:-${LOCATION}/config.json} -COMPOSE=${COMPOSE:-${LOCATION}/docker-compose.yml} +SRC=${SRC:-${LOCATION}/src} BUILD_DIR=${BUILD_DIR:-${LOCATION}/build-packages} -${LOCATION}/hosted-app-utils/package ${CONFIG} ${COMPOSE} output=${BUILD_DIR} $@ \ No newline at end of file +${LOCATION}/hosted-app-utils/package ${CONFIG} ${SRC} output=${BUILD_DIR} $@ \ No newline at end of file diff --git a/src/app.conf b/src/app.conf new file mode 100644 index 00000000..289af477 --- /dev/null +++ b/src/app.conf @@ -0,0 +1,13 @@ +{ + "name": "Streamline EMR", + "access": { + "username": "streamline_sysuser", + "password": "82CUF8UftjEx" + }, + "appconfig": { + "blockgraph": { + "district": "StreamlineEmr", + "name": "streamline_emr_config" + } + } +} \ No newline at end of file diff --git a/src/app.conf.dbsync b/src/app.conf.dbsync new file mode 100644 index 00000000..000eeacb --- /dev/null +++ b/src/app.conf.dbsync @@ -0,0 +1,30 @@ +{ + "name": "Streamline EMR", + "access": { + "username": "streamline_sysuser", + "password": "82CUF8UftjEx" + }, + "appconfig": { + "blockgraph": { + "district": "StreamlineEmr", + "name": "streamline_emr_config" + } + }, + "dbsync": { + "blockgraph": { + "district": "StreamlineEmr", + "name": "streamline_emr_data" + }, + "database": { + "type": "mysql", + "version": "8.0", + "name": "streamline", + "username": "root", + "password": "streamline", + "db_path": "/var/lib/mysql", + "logs_path": "/var/lib/mysql/logs", + "log_pattern": "bin.[0-9]*", + "source": "mysql-app-db" + } + } +} \ No newline at end of file diff --git a/docker-compose.yml b/src/docker-compose.yml similarity index 92% rename from docker-compose.yml rename to src/docker-compose.yml index b4f8e53a..8bcac24d 100755 --- a/docker-compose.yml +++ b/src/docker-compose.yml @@ -1,13 +1,12 @@ -version: "3.8" services: streamline-emr: image: ${APP_IMAGE:-streamline-emr:latest} container_name: ${APP_CONTAINER:-streamline-emr} + restart: unless-stopped volumes: - "${DATA_DIR:-./data}:/var/lib/mysql" ports: - "${APP_PORT:-3000}:80" - dns: 0.0.0.0 healthcheck: test: ["CMD", "curl", "-f", "http://localhost:80"] timeout: 30s