Skip to content

readme updates #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
smalho01 merged 2 commits into from
Feb 22, 2022
Merged

readme updates #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
23a79d1
readme updates
smalho01 Feb 22, 2022
aac95c1
Update README.md
smalho01 Feb 22, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
37 changes: 24 additions & 13 deletions DockerDevSetupGuideForMacOS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,34 +14,40 @@ This guide will take you through the development environment setup for each of t
4. [Clinical Decision Support (CDS) Library](https://github.com/mcode/CDS-Library)
5. [CRD Request Generator](https://github.com/mcode/crd-request-generator)
6. [REMS](https://github.com/mcode/REMS.git)
7. Keycloak
7. [Pharmacy Information System](https://github.com/mcode/pharmacy-information-system)
8. Keycloak

### Expected Functionality
1. File Synchronization between local host system and docker container
2. Automatic Server Reloading whenever source file is changed
- CRD also reloads on CDS_Library changes
3. Automatic Dependendency Installation whenever package.json, package-lock.json, or build.gradle are changed
4. Automatic Data Loader in test-ehr whenever fhirResourcesToLoad directory is changed
3. Automatic Dependency Installation whenever package.json, package-lock.json, or build.gradle are changed
4. Automatic Data Loader in test-ehr whenever the fhirResourcesToLoad directory is changed

## Table of Contents
- [Prerequisites](#prerequisites)
- [Install core tools](#install-core-tools)
* [Setting Environment Variables and System Path](#setting-environment-variables-and-system-path)
- [Install core tools](#install-core-tools)
* [Installing core tools on MacOS](#installing-core-tools-on-macos)
+ [Install Docker Desktop for Mac](#install-docker-desktop-for-mac)
+ [Install Ruby](#install-ruby)
+ [Install Docker-sync](#install-docker-sync)
- [Clone DRLS REMS](#clone-drls-rems)
* [Open DRLS REMS as VsCode workspace](#open-drls-rems-as-vscode-workspacey)
- [Configure DRLS REMS](#configure-drls-rems)
* [CRD configs](#crd-configs)
* [test-ehr configs](#test-ehr-configs)
* [crd-request-generator configs](#crd-request-generator-configs)
* [dtr configs](#dtr-configs)
* [rems configs](#rems-configs)

* [pharmacy-information-system configs](#pharmacy-information-system-configs)
* [Add VSAC credentials to your development environment](#add-vsac-credentials-to-your-development-environment)
- [Run DRLS REMS](#run-drls)
* [Start Docker Sync](#start-docker-sync-application)
* [Debugging docker-sync application](#debugging-docker-sync-application)
* [Stop Docker Sync](#stop-docker-sync-application-and-remove-all-containers/volumes)
* [Rebuilding Images and Containers](#rebuilding-images-and-containers)
* [Useful Docker Sync Commands](#useful-docker-sync-commands)
- [Verify DRLS is working](#verify-drls-is-working)

Expand All @@ -61,7 +67,7 @@ Additionally, you must have credentials (api key) access for the **[Value Set Au

### Setting Environment Variables and System Path

How you set environment and path variables may vary depending on your operating system and terminal used. For instance, for zsh on MacOS you typically need to modify .zshrc instead of .bash_profile. To figure out how to set environment variables for your system, consult the guides below or google `how to permentaly set environment/path variables on [insert operating system] [insert terminal type]`.
How you set environment and path variables may vary depending on your operating system and terminal used. For instance, for zsh on MacOS you typically need to modify .zshrc instead of .bash_profile. To figure out how to set environment variables for your system, consult the guides below or google `how to permanently set environment/path variables on [insert operating system] [insert terminal type]`.

For more information on how to set environment variables consult these following guides:

Expand All @@ -82,7 +88,7 @@ How you set environment and path variables may vary depending on your operating
**Note: The defaults for memory at 2GB and possibly CPU as well are too low to run the entire DRLS REMS workflow. If not enough resources are provided, you may notice containers unexpectedly crashing and stopping. Exact requirements for these resource values will depend on your machine. That said, as a baseline starting point, the system runs relatively smoothly at 15GB memory and 7 CPU Processors on MITRE issued Mac Devices.**

#### Install Visual Studio Code and Extensions
The recomended IDE for this set up is Visual Studio Code
The recommended IDE for this set up is Visual Studio Code
1. Install Visual Studio Code - https://code.visualstudio.com
2. Install Extensions - The workspace should automatically recommend extensions to install when opening the workspace

Expand All @@ -109,7 +115,7 @@ Reference: https://github.com/rbenv/rbenv
```bash
rbenv install 2.7.2
```
6. Verify that the system is using the correct ruby verions
6. Verify that the system is using the correct ruby versions
```bash
which ruby
/Users/$USER/.rbenv/shims/ruby # Correct
Expand Down Expand Up @@ -158,17 +164,18 @@ Reference: https://github.com/rbenv/rbenv
git clone https://github.com/mcode/crd-request-generator.git crd-request-generator
git clone https://github.com/mcode/dtr.git dtr
git clone https://github.com/mcode/REMS.git REMS
git clone https://github.com/mcode/pharmacy-information-system.git pharmacy-information-system

cd CRD/server
git clone https://github.com/mcode/CDS-Library.git CDS-Library
```

# Open DRLS REMS as VsCode workspace
The REMS repository contains the **REMS.code-workspace** file, which can be used to open the above project structure as a multi-root VS Code workspace. To open this workspace, select *File* > *Open Workspace from File...* and navigate to <drls-root>/REMS/REMS.code-workspace. In this workspace configuration, the CDS-Library embedded within CRD is opened as a seperate root for an easier development experience.
The REMS repository contains the **REMS.code-workspace** file, which can be used to open the above project structure as a multi-root VS Code workspace. To open this workspace, select *File* > *Open Workspace from File...* and navigate to <drls-root>/REMS/REMS.code-workspace. In this workspace configuration, the CDS-Library embedded within CRD is opened as a separate root for an easier development experience.

The Debugger Tab has various debugging configurations and can be used to easily debug any errors that come up during development. Simply start one of the debuggers and set a breakpoint anywhere in the code base. For more information on VsCode debugging see: https://code.visualstudio.com/docs/editor/debugging

The Source Control Tab can be used to easily track changes during the devlopement process and perform git actions, with each root of the workspace having its own source control header. Sor more information source control see: https://code.visualstudio.com/docs/editor/versioncontrol
The Source Control Tab can be used to easily track changes during the development process and perform git actions, with each root of the workspace having its own source control header. Sor more information source control see: https://code.visualstudio.com/docs/editor/versioncontrol

The Docker Extension for VsCode has useful functionality to aid in the development process using this set up guide. This extension lets you easily visualize the containers, images, networks, and volumes created by this set up. Clicking on a running container will open up the file structure of the container. Right clicking on a running container will give the option to view container logs (useful to see output from select services), attach a shell instance within the container, and attach a Visual Studio Code IDE to the container using remote-containers. For more information on the docker debugger see: https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker

Expand Down Expand Up @@ -196,6 +203,10 @@ The MongoDB Extension allows for connecting to the pharmacy information system's

***None***

### pharmacy-information-system configs

***None***


### Add VSAC credentials to your development environment

Expand Down Expand Up @@ -254,8 +265,8 @@ Note: Initial set up will take several minutes and spin up fans with high resour
```

### Debugging docker-sync application
1. Select the Debugger Tab on the left side pannel of VsCode
2. From the drop down menu next to Run and Debug select **Debug All REMS Applications (Docker) (workspace)**. This is a compund debugger that combines all the other docker debuggers for all servers and applications in this workspace.
1. Select the Debugger Tab on the left side panel of VsCode
2. From the drop down menu next to Run and Debug select **Debug All REMS Applications (Docker) (workspace)**. This is a compound debugger that combines all the other docker debuggers for all servers and applications in this workspace.
3. When finished debugging, simply hit the disconnect button to close out all debug sessions
4. **Important**: Make sure to close out the **Launch Chrome in Debug Mode** task that gets open in the VsCode terminal space. This task launches chrome in debug mode in order to debug frontend applications in this workspace. This needs to be closed in order to run the debugger again next time, leaving it open will not properly start the frontend debuggers.

Expand Down Expand Up @@ -285,7 +296,7 @@ or
# --no-cache Do not use cache when building the image.
# [<service_name1> <service_name2> ...] Services to recreate, not specifying any service will rebuild and recreate all services
```
After rebuilding imaages and containers, start docker-sync normally
After rebuilding images and containers, start docker-sync normally
```bash
ctrl + c # Stop running "docker-compose up" command (containers running without sync functionality)
docker-sync-stack start # If this command fails to run, running a second time usually fixes the issue
Expand All @@ -296,7 +307,7 @@ Reference: https://docker-sync.readthedocs.io/en/latest/getting-started/commands

## Verify DRLS is working

<!-- Commenting out below section as these steps have been automated as part of set up, however keeping in as a reference for how to add additonal clients to dtr -->
<!-- Commenting out below section as these steps have been automated as part of set up, however keeping in as a reference for how to add additional clients to dtr -->

<!-- ### Register the test-ehr

Expand Down
31 changes: 17 additions & 14 deletions DockerProdSetupGuideForMacOS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,9 @@

This document details the installation process for the dockerized version of the **Documentation Requirements Lookup Service (DRLS) REMS Workflow** system for Production. There are two approaches to doing this:

Option 1 utilizes Docker Compose, which comes with Docker Dektop, and requires the corresponding docker-compose.yml file from the REMS repository. This option has minimal technical set up involved and allows for the customization/modification of the dockerized configuration.
Option 1 utilizes Docker Compose, which comes with Docker Desktop, and requires the corresponding docker-compose.yml file from the REMS repository. This option has minimal technical set up involved and allows for the customization/modification of the dockerized configuration.

Option 2 utilizes Porter, which requires a seperate installation in addition to Docker Desktop but does not require the use of any local files. This option has the least amount of technical set up involved and is recommended for non-tecnical users of DRLS REMS as it **does not** allow for the customization/modification of the dockerized configuration.
Option 2 utilizes Porter, which requires a separate installation in addition to Docker Desktop but does not require the use of any local files. This option has the least amount of technical set up involved and is recommended for non-technical users of DRLS REMS as it **does not** allow for the customization/modification of the dockerized configuration.

This document **is designed to take you through the entire set up process for DRLS REMS using docker containers**. It is a standalone guide that does not depend on any supplementary DRLS REMS documentation.

Expand All @@ -16,19 +16,22 @@ This guide will take you through the development environment setup for each of t
3. [Documents, Templates, and Rules (DTR) SMART on FHIR app](https://github.com/mcode/dtr)
4. [Clinical Decision Support (CDS) Library](https://github.com/mcode/CDS-Library)
5. [CRD Request Generator](https://github.com/mcode/crd-request-generator)
6. [REMS](https://github.com/mcode/REMS.git)
7. Keycloak
6. [REMS](https://github.com/mcode/REMS)
7. [Pharmacy Information System](https://github.com/mcode/pharmacy-information-system)
8. Keycloak

## Table of Contents
- [Prerequisites](#prerequisites)
* [Setting Environment Variables and System Path](#setting-environment-variables-and-system-path)
- [Install core tools](#install-core-tools)
* [Installing core tools on MacOS](#installing-core-tools-on-macos)
+ [Install Docker Desktop for Mac](#install-docker-desktop-for-mac)
+ [Install Porter (Option 2 only)](#install-porter-(option-2-only))
- [Clone REMS repository(Option 1 Only)](#clone-rems-repository-(option-1-only))
+ [Install Porter (Option 2 only)](#install-porter-option-2-only)
- [Clone REMS repository(Option 1 Only)](#clone-rems-repository-option-1-only)
* [Open REMS in VSCode (Option 1 Only)](#open-rems-in-vscode-option-1-only)
- [Configure DRLS REMS](#configure-drls-rems)
* [Add VSAC credentials to environment (Option 1 only)](#add-vsac-credentials-to-environment-(option-1-only))
* [Add Compose Project Name to environment (Option 1 only)](#add-compose-project-name-to-environment-(option-1-only))
* [Add VSAC credentials to environment (Option 1 only)](#add-vsac-credentials-to-environment-option-1-only)
* [Add Compose Project Name to environment (Option 1 only)](#add-compose-project-name-to-environment-option-1-only)
- [Run DRLS REMS](#run-drls-rems)
* [Option 1 - Docker Compose](#option-1---docker-compose)
* [Option 2 - Porter Install](#option-2---porter-install)
Expand All @@ -50,7 +53,7 @@ Additionally, you must have credentials (api key) access for the **[Value Set Au

### Setting Environment Variables and System Path

How you set environment and path variables may vary depending on your operating system and terminal used. For instance, for zsh on MacOS you typically need to modify .zshrc instead of .bash_profile. To figure out how to set environment variables for your system, consult the guides below or google `how to permentaly set environment/path variables on [insert operating system] [insert terminal type]`.
How you set environment and path variables may vary depending on your operating system and terminal used. For instance, for zsh on MacOS you typically need to modify .zshrc instead of .bash_profile. To figure out how to set environment variables for your system, consult the guides below or google `how to permanently set environment/path variables on [insert operating system] [insert terminal type]`.

For more information on how to set environment variables consult these following guides:

Expand Down Expand Up @@ -109,9 +112,9 @@ The recomended IDE for this set up is Visual Studio Code
git clone https://github.com/mcode/REMS.git REMS
```

Alternatively, you can download/copy just the docker-compose.yml file from the REMS reposiotry since that is the only file needed for this set up.
Alternatively, you can download/copy just the docker-compose.yml file from the REMS repository since that is the only file needed for this set up.

## Open REMS in VSCode (Option 1 Only)
### Open REMS in VSCode (Option 1 Only)

The Docker Extension for VsCode has useful functionality to aid in the development process using this set up guide. This extension lets you eaily visualize the containers, images, networks, and volumes created by this set up. Clicking on a running container will open up the file structure of the container. Right clicking on a running container will give the option to view container logs (useful to see output from select services), attach a shell instance within the container, and attach a Visual Studio Code IDE to the container using remote-containers. See: https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker

Expand Down Expand Up @@ -145,7 +148,7 @@ Note: How you set environment and path variables may vary depending on your oper

### Add Compose Project Name to environment (Option 1 only)

Note: The compose project name is to disambiguate between different set ups on the same machine and can be set to any identifier. If you are following both options mentioned in this guide, it is reccomended to change the compose project name for each so that they differ.
Note: The compose project name is to disambiguate between different set ups on the same machine and can be set to any identifier. If you are following both options mentioned in this guide, it is recommended to change the compose project name for each so that they differ.

You can see a list of your pre-existing environment variables on your Mac by running `env` in your Terminal. To add to `env`:
1. Set "COMPOSE_PROJECT_NAME" as "rems_prod" in the .env file in the REMS Repository
Expand Down Expand Up @@ -242,7 +245,7 @@ If you get the below error on running the stop command above, then try running t

or

porter upgrade fullstack_rems --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvlatest # Pull and Update Invocation Image in addition to applicaion images from remote repository and recreate containers
porter upgrade fullstack_rems --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvlatest # Pull and Update Invocation Image in addition to application images from remote repository and recreate containers
```

#### Uninstall Porter Application
Expand Down Expand Up @@ -272,7 +275,7 @@ To remove all images, volumes, and artifacts set up during the install, run the

## Verify DRLS is working

<!-- Commenting out below section as these steps have been automated as part of set up, however keeping in as a reference for how to add additonal clients to dtr -->
<!-- Commenting out below section as these steps have been automated as part of set up, however keeping in as a reference for how to add additional clients to dtr -->

<!-- ### Register the test-ehr

Expand Down
2 changes: 1 addition & 1 deletion README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ You can find complete end-to-end fullstack set up guides for DRLS REMS at the fo

[Developer Environment Set Up](DockerDevSetupGuideForMacOS.md) - Follow this guide if you are a developer and intend on making code changes to the DRLS REMS project. This guide follows a much more technical set up process.

[Production Environement Set Up](DockerProdSetupGuideForMacOS.md) - Follow this guide if you are not a developer and do not intend on making code changes to the DRLS REMS project. This guide covers two options for running DRLS REMS, both of which are less techincal than the developer set up.
[Production Environment Set Up](DockerProdSetupGuideForMacOS.md) - Follow this guide if you are not a developer and do not intend on making code changes to the DRLS REMS project. This guide covers two options for running DRLS REMS, both of which are less technical than the developer set up.

## Running REMS server locally
1. Clone the REMS repositories from Github:
Expand Down