diff --git a/DockerDevSetupGuideForMacOS.md b/DeveloperSetupGuide.md similarity index 84% rename from DockerDevSetupGuideForMacOS.md rename to DeveloperSetupGuide.md index f2bdf306..92574371 100644 --- a/DockerDevSetupGuideForMacOS.md +++ b/DeveloperSetupGuide.md @@ -2,7 +2,7 @@ ## Purpose of this guide -This document details the installation process for the dockerized version of the **Documentation Requirements Lookup Service (DRLS) REMS Workflow** system for Local Development. Be aware that each component of DRLS has its own README where you will find more detailed documentation. This document **is not designed to replace those individual READMEs**. +This document details the installation process for the dockerized version of the **Documentation Requirements Lookup Service (DRLS) REMS Workflow** system for Local Development. Be aware that each component of DRLS has its own README where you will find more detailed documentation. This document **is not designed to replace those individual READMEs**. This document **is designed to take you through the entire set up process for DRLS using docker containers**. It is a standalone guide that does not depend on any supplementary DRLS documentation. @@ -15,7 +15,7 @@ This guide will take you through the development environment setup for each of t 5. [CRD Request Generator](https://github.com/mcode/crd-request-generator) 6. [REMS](https://github.com/mcode/REMS.git) 7. [Pharmacy Information System](https://github.com/mcode/pharmacy-information-system) -8. Keycloak +8. [Keycloak](https://www.keycloak.org/) ### Expected Functionality 1. File Synchronization between local host system and docker container @@ -56,14 +56,21 @@ This guide will take you through the development environment setup for each of t Your computer must have these minimum requirements: - x86_64 (64-bit) or equivalent processor - * Follow these instructions to verify your machine's compliance: https://www.macobserver.com/tips/how-to/mac-32-bit-64-bit/ -- At least 8 GB of RAM + * Follow these instructions to verify your machine's compliance: https://www.macobserver.com/tips/how-to/mac-32-bit-64-bit/ +- At least 16 GB of RAM (12 GB recommended minimum for Docker Desktop) - At least 256 GB of storage - Internet access - [Chrome browser](https://www.google.com/chrome/) - [Git installed](https://www.atlassian.com/git/tutorials/install-git) -Additionally, you must have credentials (api key) access for the **[Value Set Authority Center (VSAC)](https://vsac.nlm.nih.gov/)**. Later on you will add these credentials to your development environment, as they are required for allowing DRLS to pull down updates to value sets that are housed in VSAC. If you don't already have VSAC credentials, you should [create them using UMLS](https://www.nlm.nih.gov/research/umls/index.html). +Obtain [Value Set Authority Center (VSAC)](https://vsac.nlm.nih.gov/) API key + 1. [Click here](https://www.nlm.nih.gov/research/umls/index.html) to read about UMLS + 2. Click 'request a license' under 'Get Started' + 3. If you already have a key you can click 'Visit Your Profile' in the right hand side-bar. The API key will be listed under your username. + 4. If you do not have a key, click 'Generate an API Key' + 5. Sign in using one of the providers (Login.gov recommended) + 6. Generating the key is an automated process, you should be approved via e-mail fairly quickly. If not, use the contact information in the first link to reach out to the office (this is not managed by our team / system). + 7. Once approved, loop back to step 2 ### Setting Environment Variables and System Path @@ -77,23 +84,23 @@ How you set environment and path variables may vary depending on your operating ## Install core tools -### Installing core tools on MacOS +### Installing core tools -#### Install Docker Desktop for Mac +#### Install Docker Desktop -1. Download the **stable** version of **[Docker for Mac](https://www.docker.com/products/docker-desktop)** and follow the steps in the installer. -2. Once the installation is complete, you should see a Docker icon on your Mac's menu bar (top of the screen). Click the icon and verify that **Docker Desktop is running.** -3. Configure Docker to have access to enough resources. To do this, open Docker Desktop and select Settings > Resources. +1. Download the **stable** version of **[Docker Desktop](https://www.docker.com/products/docker-desktop)** and follow the steps in the installer. +2. Once the installation is complete, verify that **Docker Desktop is running.** +3. Configure Docker to have access to enough resources. To do this, open Docker Desktop and select Settings > Resources. - **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.** + **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 6 CPU Processors on MITRE issued Mac Devices.** #### Install Visual Studio Code and Extensions 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 -#### Install Ruby -Note: The default ruby that comes with Mac may not install the right package version for docker-sync, it is reccomended to install ruby with a package manager, this guide uses rbenv. +#### Install Ruby +Note: The default ruby that comes with Mac may not install the right package version for docker-sync, it is reccomended to install ruby with a package manager, this guide uses rbenv. Reference: https://github.com/rbenv/rbenv @@ -107,47 +114,47 @@ Reference: https://github.com/rbenv/rbenv rbenv init ``` 3. Close Terminal so changes take affect -4. Test rbenv is installed correctly +4. Test rbenv is installed correctly ```bash curl -fsSL https://github.com/rbenv/rbenv-installer/raw/main/bin/rbenv-doctor | bash ``` -5. Install Ruby +5. Install Ruby ```bash - rbenv install 2.7.2 + rbenv install 2.7.2 ``` -6. Verify that the system is using the correct ruby versions +6. Verify that the system is using the correct ruby versions ```bash which ruby /Users/$USER/.rbenv/shims/ruby # Correct .... - which ruby + which ruby /usr/bin/ruby # Incorrect, using system default ruby. Path not set correctly, reference step 2 ``` -#### Install Docker-sync +#### Install Docker-sync 1. Download and Install docker-sync using the following command: ```bash gem install docker-sync -v 0.7.0 ``` -2. Test that the right version is installed +2. Test that the right version is installed ```bash docker-sync -v - 0.7.0 # Correct + 0.7.0 # Correct ... docker-sync -v - 0.1.1 # Incorrect, make sure you have ruby installed and are not using the default system ruby + 0.1.1 # Incorrect, make sure you have ruby installed and are not using the default system ruby ``` Note: The versioning is important, system default ruby sometimes installs version 0.1.1 if -v tag is not set. The 0.1.1 release will not work for the rest of this guide. ## Clone DRLS REMS -1. Create a root directory for the DRLS development work (we will call this `` for the remainder of this setup guide). While this step is not required, having a common root for the DRLS components will make things a lot easier down the line. +1. Create a root directory for the DRLS development work (we will call this `` for the remainder of this setup guide). While this step is not required, having a common root for the DRLS components will make things a lot easier down the line. ```bash mkdir ``` @@ -170,42 +177,17 @@ Reference: https://github.com/rbenv/rbenv 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 /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. +# Open DRLS REMS as VsCode workspace -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 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 /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 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 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 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 - -The MongoDB Extension allows for connecting to the pharmacy information system's backend database by inputting the following connection string: `mongodb://pharmacy-information-root:pharmacy-information-password@localhost:27017/?retryWrites=true&w=majority`. For more information on this extension see: https://marketplace.visualstudio.com/items?itemName=mongodb.mongodb-vscode - -## Configure DRLS REMS - -### CRD configs - -***None*** - -### test-ehr configs - -***None*** - -### crd-request-generator configs - -***None*** - -### dtr configs - -***None*** +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 -### REMS configs - -***None*** - -### pharmacy-information-system configs +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 -***None*** +The MongoDB Extension allows for connecting to the pharmacy information system's backend database by inputting the following connection string: `mongodb://pharmacy-information-root:pharmacy-information-password@localhost:27017/?retryWrites=true&w=majority`. For more information on this extension see: https://marketplace.visualstudio.com/items?itemName=mongodb.mongodb-vscode ### Add VSAC credentials to your development environment @@ -213,19 +195,19 @@ The MongoDB Extension allows for connecting to the pharmacy information system's > At this point, you should have credentials to access VSAC. If not, please refer to [Prerequisites](#prerequisites) for how to create these credentials and return here after you have confirmed you can access VSAC. > To download the full ValueSets, your VSAC account will need to be added to the CMS-DRLS author group on https://vsac.nlm.nih.gov/. You will need to request membership access from an admin. Please reach out to Sahil Malhotra at smalhotra@mitre.org in order to request access to the CMS-DRLS author group. If this is not configured, you will get `org.hl7.davinci.endpoint.vsac.errors.VSACValueSetNotFoundException: ValueSet 2.16.840.1.113762.1.4.1219.62 Not Found` errors. -> While this step is optional, we **highly recommend** that you do it so that DRLS will have the ability to dynamically load value sets from VSAC. +> While this step is optional, we **highly recommend** that you do it so that DRLS will have the ability to dynamically load value sets from VSAC. 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 "VSAC_API_KEY" in the .env file in the REMS Repository +1. Set "VSAC_API_KEY" in the .env file in the REMS Repository - or + or 1. `cd ~/` 2. Open `.bash_profile` and add the following lines at the very bottom: ```bash export VSAC_API_KEY=vsac_api_key ``` -3. Save `.bash_profile` and complete the update to `env`: +3. Save `.bash_profile` and complete the update to `env`: ```bash source .bash_profile ``` @@ -235,19 +217,19 @@ You can see a list of your pre-existing environment variables on your Mac by run Note: How you set environment and path variables may vary depending on your operating system and terminal used. See [Setting Environment Variables and System Path](#setting-environment-variables-and-system-path) for more information. -### Add Compose Project Name +### Add Compose Project Name 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_dev" in the .env file in the REMS Repository +1. Set "COMPOSE_PROJECT_NAME" as "rems_dev" in the .env file in the REMS Repository + + or - or - 1. `cd ~/` 2. Open `.bash_profile` and add the following lines at the very bottom: ```bash export COMPOSE_PROJECT_NAME=rems_dev ``` -3. Save `.bash_profile` and complete the update to `env`: +3. Save `.bash_profile` and complete the update to `env`: ```bash source .bash_profile ``` @@ -257,8 +239,8 @@ Note: How you set environment and path variables may vary depending on your oper ## Run DRLS -### Start docker-sync application -Note: Initial set up will take several minutes and spin up fans with high resource use, be patient, future boots will be much quicker, quieter, and less resource intensive +### Start docker-sync application +Note: Initial set up will take several minutes and spin up fans with high resource use, be patient, future boots will be much quicker, quieter, and less resource intensive ```bash docker-sync-stack start # This is the equivalent of running docker-sync start followed by docker-compose up @@ -268,7 +250,7 @@ Note: Initial set up will take several minutes and spin up fans with high resour 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. +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. ![Closing Launch Chrome Task](./setup-images/ClosingLaunchChromeTask.png) @@ -307,17 +289,6 @@ Reference: https://docker-sync.readthedocs.io/en/latest/getting-started/commands ## Verify DRLS is working - - - - ### The fun part: Generate a test request 1. Go to http://localhost:3000/ehr-server/reqgen. @@ -334,17 +305,13 @@ Note: Do not click the X that shows up next to **http://localhost:8080/test-ehr/ 10. A webpage should open in a new tab, and after a few seconds, a questionnaire should appear. 11. Fill out questionnaire and hit **Proceed to Prior Auth**. 12. Click **submit** to send prescription request to pharmacist (note: this is a stand in ui and there is no visual that anything happens after hitting the submit button). - 13. Go to http://localhost:4200 and play the role of a pharmacist. 14. Click on **Log in as Admin** in the top right of the page 15. If you've already created login credentials, then sign in with those credentials and skip to step 17. If not, proceed to step 16. -16. Click **Sign Up** at the bottom of the screen and create some credentials for yourself. Select pharmacist as your role and fill in some example data for the rest of the fields. Click **submit** to create your account, there is no visual that anything happens after hitting submit. Finally, click on **Login** at the bottom of the screen and go back to step 15. -17. Click **Doctor Orders** in the left hand navigation menu on the screen +16. Click **Sign Up** at the bottom of the screen and create some credentials for yourself. Select pharmacist as your role and fill in some example data for the rest of the fields. Click **submit** to create your account, there is no visual that anything happens after hitting submit. Finally, click on **Login** at the bottom of the screen and go back to step 15. +17. Click **Doctor Orders** in the left hand navigation menu on the screen 18. See the Doctor Order that was sent to the pharmacist from the prescriber in steps 1-12. - - - Congratulations! DRLS is fully installed and ready for you to use! ## Troubleshooting docker-sync diff --git a/DockerProdSetupGuideForMacOS.md b/DockerProdSetupGuideForMacOS.md deleted file mode 100644 index 66895340..00000000 --- a/DockerProdSetupGuideForMacOS.md +++ /dev/null @@ -1,317 +0,0 @@ -# DRLS-REMS-Docker-The Ultimate Guide to Running DRLS REMS locally - -## Purpose of this guide - -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 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 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. - -This guide will take you through the development environment setup for each of the following DRLS components: -1. [Coverage Requirements Discovery (CRD)](https://github.com/mcode/CRD) -2. [(Test) EHR FHIR Service](https://github.com/HL7-DaVinci/test-ehr) -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) -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) - * [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) -- [Run DRLS REMS](#run-drls-rems) - * [Option 1 - Docker Compose](#option-1---docker-compose) - * [Option 2 - Porter Install](#option-2---porter-install) -- [Verify DRLS is working](#verify-drls-is-working) - - -## Prerequisites - -Your computer must have these minimum requirements: -- x86_64 (64-bit) or equivalent processor - * Follow these instructions to verify your machine's compliance: https://www.macobserver.com/tips/how-to/mac-32-bit-64-bit/ -- At least 8 GB of RAM -- At least 256 GB of storage -- Internet access -- [Chrome browser](https://www.google.com/chrome/) -- [Git installed](https://www.atlassian.com/git/tutorials/install-git) - -Additionally, you must have credentials (api key) access for the **[Value Set Authority Center (VSAC)](https://vsac.nlm.nih.gov/)**. Later on you will add these credentials to your development environment, as they are required for allowing DRLS to pull down updates to value sets that are housed in VSAC. If you don't already have VSAC credentials, you should [create them using UMLS](https://www.nlm.nih.gov/research/umls/index.html). - -### 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 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: - - - https://chlee.co/how-to-setup-environment-variables-for-windows-mac-and-linux/ - - https://www3.ntu.edu.sg/home/ehchua/programming/howto/Environment_Variables.html - - https://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables - -## Install core tools - -### Installing core tools on MacOS - -#### Install Docker Desktop for Mac - -1. Download the **stable** version of **[Docker for Mac](https://www.docker.com/products/docker-desktop)** and follow the steps in the installer. -2. Once the installation is complete, you should see a Docker icon on your Mac's menu bar (top of the screen). Click the icon and verify that **Docker Desktop is running.** -3. Configure Docker to have access to enough resources. To do this, open Docker Desktop and select Settings > Resources. - - 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 16GB memory and 6 CPU Processors on MITRE issued Mac Devices. - -#### Install Visual Studio Code and Extensions (Option 1 Only) - -The recomended IDE for this set up is Visual Studio Code - -1. Install Visual Studio Code - https://code.visualstudio.com -2. Install Docker extension - https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker - -#### Install Porter (Option 2 Only) - -1. Download and install porter as per https://porter.sh/install/ instructions: - ```bash - curl -L https://cdn.porter.sh/latest/install-mac.sh | bash - ``` -2. Open `.bash_profile` and add the following lines at the very bottom: - ```bash - export PATH=$PATH:~/.porter - ``` - - Note: The exact command to add to your system path will be mentioned at the bottom of the execution of step 1 and may vary from what's above depending the operating system you installed Porter on. Consult the output in your terminal for how to set your system path. - - Note: How you set environment and path variables may vary depending on your operating system and terminal used. See [Setting Environment Variables and System Path](#setting-environment-variables-and-system-path) for more information. - -3. Save `.bash_profile` or whatever file was modified in step 2 and complete the update to your `environment`: - ```bash - source .bash_profile - ``` -4. Install required Porter plugins - ```bash - porter mixins install docker - porter mixins install docker-compose - ``` - -## Clone REMS repository (Option 1 Only) - -1. clone the REMS repositories from Github: - ```bash - git clone https://github.com/mcode/REMS.git REMS - ``` - - 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) - -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 - -## Configure DRLS REMS - -### Add VSAC credentials to environment (Option 1 only) - -> At this point, you should have credentials to access VSAC. If not, please refer to [Prerequisites](#prerequisites) for how to create these credentials and return here after you have confirmed you can access VSAC. If this is not configured, you will get `org.hl7.davinci.endpoint.vsac.errors.VSACValueSetNotFoundException: ValueSet 2.16.840.1.113762.1.4.1219.62 Not Found` errors. - -> While this step is optional, we **highly recommend** that you do it so that DRLS will have the ability to dynamically load value sets from VSAC. - -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 "VSAC_API_KEY" in the .env file in the REMS Repository - -or - -1. `cd ~/` -2. Open `.bash_profile` and add the following lines at the very bottom: - ```bash - export VSAC_API_KEY=vsac_api_key - ``` -3. Save `.bash_profile` and complete the update to `env`: - ```bash - source .bash_profile - ``` - -> Be aware that if you have chosen to skip this step, you will be required to manually provide your VSAC credentials at http://localhost:8090/data and hit **Reload Data** every time you want DRLS to use new or updated value sets. - -Note: How you set environment and path variables may vary depending on your operating system and terminal used. See [Setting Environment Variables and System Path](#setting-environment-variables-and-system-path) for more information. - -### 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 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 - -or - -1. `cd ~/` -2. Open `.bash_profile` and add the following lines at the very bottom: - ```bash - export COMPOSE_PROJECT_NAME=rems_prod - ``` -3. Save `.bash_profile` and complete the update to `env`: - ```bash - source .bash_profile - ``` - -Note: How you set environment and path variables may vary depending on your operating system and terminal used. See [Setting Environment Variables and System Path](#setting-environment-variables-and-system-path) for more information. - -## Run DRLS REMS -### Option 1 - Docker Compose -#### Start docker compose application - -```bash - cd REMS # Need to execute commands in directory with corresponding docker-compose.yml file located in the REMS repository - docker-compose up -``` - -#### Stop docker-compose and uninstall application -```bash - docker-compose down # Removes application servers -``` - -To remove all images, volumes, and artifacts set up during the install, run the following commands - -```bash - docker image prune -a - docker volume prune - docker network prune -``` - -#### Updating docker-compose application images - -```bash - docker-compose build --no-cache --pull [ ...] - docker-compose --force-recreate [ ...] -``` - -```bash - - # Options: - # --force-recreate Recreate containers even if their configuration and image haven't changed. - # --build Build images before starting containers. - # --pull Pull published images before building images. - # --no-cache Do not use cache when building the image. - # [ ...] Services to recreate, not specifying any service will rebuild and recreate all services -``` - -### Option 2 - Porter Install -#### Install and Run Porter application - -You can set the flag --allow-docker-host-access in the below commands with the PORTER_ALLOW_DOCKER_HOST_ACCESS environment variable so that you don’t have to specify it for every command. - -Note: replace ${vsac_api_key} in the below commands with your own vsac api key. If you do not have access to VSAC, please refer to [Prerequisites](#prerequisites) for how to create these credentials and return here after you have confirmed you can access VSAC. - -```bash - porter install fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvCurrent # Initial Installation needs to be from remote repository - - or - - porter install fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access # Subsequent runs can use the local installation - -``` -Note: The project will keep running in the background when you "ctrl + c" out of the above process. To stop running all together, use the stop command below - -#### Stop Running Porter application -```bash - porter invoke fullstack_rems --action stop --param vsac_api_key=${vsac_api_key} --allow-docker-host-access -``` - -If you get the below error on running the stop command above, then try running the stop command with the **--reference** field as so - -```bash - - Unable to find image 'codexrems/fullstack_rems-installer:v0.0.1' locally - Error: 1 error occurred: - * Error response from daemon: manifest for codexrems/fullstack_rems-installer:v0.0.1 not found: manifest unknown: manifest unknown - - - porter invoke fullstack_rems --action stop --param vsac_api_key=${vsac_api_key} --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvCurrent -``` - -#### Updating Porter application - -```bash - porter upgrade fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access # Pull and Update application images and recreate containers - - or - - porter upgrade fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvCurrent # Pull and Update Invocation Image in addition to application images from remote repository and recreate containers -``` - -#### Uninstall Porter Application -```bash - porter uninstall fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access -``` - -If you get the below error on running the stop command above, then try running the stop command with the **--reference** field as so - -```bash - - Unable to find image 'codexrems/fullstack_rems-installer:v0.0.1' locally - Error: 1 error occurred: - * Error response from daemon: manifest for codexrems/fullstack_rems-installer:v0.0.1 not found: manifest unknown: manifest unknown - - - porter uninstall fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvCurrent -``` - -To remove all images, volumes, and artifacts set up during the install, run the following commands - -```bash - docker image prune -a - docker volume prune - docker network prune -``` - -## Verify DRLS is working - - - - - -### The fun part: Generate a test request - - -1. Go to http://localhost:3000 and play the role of a prescriber. -2. Click **Patient Select** button in upper left. -3. Find **Jon Snow** in the list of patients and click the dropdown menu next to his name. -4. Select **2183126 - Turalio 200 MG Oral Capsule** in the dropdown menu. -5. Click anywhere in the row to select Jon Snow. -6. Click **Submit** at the bottom of the page. -7. After several seconds you should receive a response in the form of a **CDS card**: - - **Drug Has REMS: Documentation Required.** -8. Select **Patient Enrollment Form** on the returned CDS card. -9. If you are asked for login credentials, use **alice** for username and **alice** for password. -10. A webpage should open in a new tab, and after a few seconds, a questionnaire should appear. -11. Fill out questionnaire and hit **Proceed to Prior Auth**. -12. Click **submit** to send prescription request to pharmacist (note: this is a stand in ui and there is no visual that anything happens after hitting the submit button). - -13. Go to http://localhost:4200 and play the role of a pharmacist. -14. Click on **Log in as Admin** in the top right of the page -15. If you've already created login credentials, then sign in with those credentials and skip to step 17. If not, proceed to step 16. -16. Click **Sign Up** at the bottom of the screen and create some credentials for yourself. Select pharmacist as your role and fill in some example data for the rest of the fields. Click **submit** to create your account, there is no visual that anything happens after hitting submit. Finally, click on **Login** at the bottom of the screen and go back to step 15. -17. Click **Doctor Orders** in the left hand navigation menu on the screen -18. See the Doctor Order that was sent to the pharmacist from the prescriber in steps 1-12. - - - - -Congratulations! DRLS is fully installed and ready for you to use! diff --git a/README.md b/README.md index 5d0d8906..a2fd8a2e 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ # REMS -## Running fullstack DRLS REMS Dockerized set up +## Running the full prototype environment -You can find complete end-to-end fullstack set up guides for DRLS REMS at the following links: +You can find complete end-to-end full-stack set up guides for DRLS REMS at the following links: -[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 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. +[Simple Set Up](SimpleSetupGuide.md) - This guide will get you up and running quickly with a demo environment for using the prototype locally. If you want to make changes or contribute to the codebase, see the detailed developer guide below. -## Running REMS server locally +[Developer Environment Set Up](DeveloperSetupGuide.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 and is fully featured. + +## Running only the REMS server project locally 1. Clone the REMS repositories from Github: ```bash git clone https://github.com/mcode/REMS.git REMS diff --git a/SimpleSetupGuide.md b/SimpleSetupGuide.md new file mode 100644 index 00000000..756a6ff2 --- /dev/null +++ b/SimpleSetupGuide.md @@ -0,0 +1,225 @@ +# DRLS REMS Local Demo Setup Guide + +## Guide Contents +- [Purpose](#purpose-of-this-guide) +- [Components](#components) +- [Quick Setup](#quick-setup) +- [Cleanup and Useful Options](#cleanup-and-useful-commands) + * [Setting Environment Variables](#setting-environment-variables) + * [Configurable install](docker-compose-without-porter) + +## Purpose of this guide + +This document details instructions on how to quickly get up and running with a local demo deployment of the full-stack Documentation Requirements Lookup Service (DRLS) REMS prototype environment. This is primarily meant for non-technical users interested in exploring the prototype on their own machine. + +*Note:* If you are looking to contribute or make code changes, please see the full [Developer Environment Setup](DeveloperSetupGuide.md). + +*Note:* If you are looking to just have more control or configuration options with Docker in your local environment, see [the configurable install](docker-compose-without-porter). + +## Components + +The following DRLS components will be deployed in Docker locally: + +1. [Coverage Requirements Discovery (CRD)](https://github.com/mcode/CRD) +2. [(Test) EHR FHIR Service](https://github.com/HL7-DaVinci/test-ehr) +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) +7. [Pharmacy Information System](https://github.com/mcode/pharmacy-information-system) +8. [Keycloak](https://www.keycloak.org/) + +## Quick Setup + +### 1. Verify or Install Prerequisites + +#### System Requirements +Your computer must have these minimum requirements: +- x86_64 (64-bit) or equivalent processor +- At least 12 GB of RAM +- At least 256 GB of storage +- Internet access +- [Chrome browser](https://www.google.com/chrome/) installed +- **[Docker Desktop](https://www.docker.com/products/docker-desktop)** installed - after installing ensure it is running using their setup guide. For resources, the system requires more than the default. Click the settings cog and go to resources. Allocate 8GB+ of RAM (16GB is ideal), and 4+ CPUs. +- [Porter Install](https://porter.sh/install/) - *Note:* read the output from the installation as once it is finished, depending on Operating System, it may tell you to run additional commands to finish the setup. +- [Porter Mixins](https://porter.sh/mixins/) - Install `docker` and `docker-compose` mixins for porter. To install from terminal: +```bash + porter mixins install docker + porter mixins install docker-compose +``` + +### 2. Obtain [Value Set Authority Center (VSAC)](https://vsac.nlm.nih.gov/) API key + 1. [Click here](https://www.nlm.nih.gov/research/umls/index.html) to read about UMLS + 2. Click 'request a license' under 'Get Started' + 3. If you already have a key you can click 'Visit Your Profile' in the right hand side-bar. The API key will be listed under your username. + 4. If you do not have a key, click 'Generate an API Key' + 5. Sign in using one of the providers (Login.gov recommended) + 6. Generating the key is an automated process, you should be approved via e-mail fairly quickly. If not, use the contact information in the first link to reach out to the office (this is not managed by our team / system). + 7. Once approved, loop back to step 2 + +### 3. Run + +> Note: replace ${vsac_api_key} in the below commands with your own VSAC api key obtained in the previous step. + +```bash + # First time run + porter install fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvCurrent # Initial Installation needs to be from remote repository + + # Future runs + porter install fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access # Subsequent runs can use the local installation +``` + +### 4. Verify everything is working + +### The fun part: Generate a test request + +1. Go to http://localhost:3000 and play the role of a prescriber. +2. Click **Patient Select** button in upper left. +3. Find **Jon Snow** in the list of patients and click the dropdown menu next to his name. +4. Select **2183126 - Turalio 200 MG Oral Capsule** in the dropdown menu. +5. Click anywhere in the row to select Jon Snow. +6. Click **Submit** at the bottom of the page. +7. After several seconds you should receive a response in the form of a **CDS card**: + - **Drug Has REMS: Documentation Required.** +8. Select **Patient Enrollment Form** on the returned CDS card. +9. If you are asked for login credentials, use **alice** for username and **alice** for password. +10. A webpage should open in a new tab, and after a few seconds, a questionnaire should appear. +11. Fill out questionnaire and hit **Proceed to Prior Auth**. +12. Click **submit** to send prescription request to pharmacist (note: this is a stand in ui and there is no visual that anything happens after hitting the submit button). +13. Go to http://localhost:4200 and play the role of a pharmacist. +14. Click on **Log in as Admin** in the top right of the page +15. If you've already created login credentials, then sign in with those credentials and skip to step 17. If not, proceed to step 16. +16. Click **Sign Up** at the bottom of the screen and create some credentials for yourself. Select pharmacist as your role and fill in some example data for the rest of the fields. Click **submit** to create your account, there is no visual that anything happens after hitting submit. Finally, click on **Login** at the bottom of the screen and go back to step 15. +17. Click **Doctor Orders** in the left hand navigation menu on the screen +18. See the Doctor Order that was sent to the pharmacist from the prescriber in steps 1-12. + +Congratulations! DRLS is fully installed and ready for you to use! + + +## Cleanup and Useful Options + +### Stop Server + +Stop Running Porter application by running: + +```bash + porter invoke fullstack_rems --action stop --param vsac_api_key=${vsac_api_key} --allow-docker-host-access +``` + +If you get the below error on running the stop command above, then try running the stop command with the **--reference** field as so + +```bash + + Unable to find image 'codexrems/fullstack_rems-installer:v0.0.1' locally + Error: 1 error occurred: + * Error response from daemon: manifest for codexrems/fullstack_rems-installer:v0.0.1 not found: manifest unknown: manifest unknown + + porter invoke fullstack_rems --action stop --param vsac_api_key=${vsac_api_key} --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvCurrent +``` + +### Updating Porter application + +```bash + porter upgrade fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access # Pull and Update application images and recreate containers + + or + + porter upgrade fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvCurrent # Pull and Update Invocation Image in addition to application images from remote repository and recreate containers +``` + +### Cleanup +```bash + porter uninstall fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access +``` + +If you get the below error on running the stop command above, then try running the stop command with the **--reference** field as so + +```bash + + Unable to find image 'codexrems/fullstack_rems-installer:v0.0.1' locally + Error: 1 error occurred: + * Error response from daemon: manifest for codexrems/fullstack_rems-installer:v0.0.1 not found: manifest unknown: manifest unknown + + + porter uninstall fullstack_rems --param vsac_api_key=${vsac_api_key} --allow-docker-host-access --reference codexrems/fullstack_rems:REMSvCurrent +``` + +To remove all images, volumes, and artifacts set up during the install, run the following commands + +```bash + docker image prune -a + docker volume prune + docker network prune +``` + +### Setting Environment Variables + +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: + + - https://chlee.co/how-to-setup-environment-variables-for-windows-mac-and-linux/ + - https://www3.ntu.edu.sg/home/ehchua/programming/howto/Environment_Variables.html + - https://unix.stackexchange.com/questions/117467/how-to-permanently-set-environmental-variables + + > At this point, you should have credentials to access VSAC. If not, please refer to step 2 of [quick setup](#quick-setup) for how to create these credentials and return here after you have confirmed you can access VSAC. If this is not configured, you will get `org.hl7.davinci.endpoint.vsac.errors.VSACValueSetNotFoundException: ValueSet 2.16.840.1.113762.1.4.1219.62 Not Found` errors. + + > While this step is optional, we **highly recommend** that you do it so that DRLS will have the ability to dynamically load value sets from VSAC. + +Set `VSAC_API_KEY` in your terminal environment to the API key obtained from your [UMLS profile page](https://uts.nlm.nih.gov/uts/edit-profile) - for more info on getting your VSAC key see [step 2 of quick setup section](#quick-setup). For setting up your environment, see the [Setting Environment Variables](#setting-environment-variables) section. + +Bash example: + ```bash + export VSAC_API_KEY=vsac_api_key + ```` + +### Docker Compose without Porter + +If you are looking for more options / customized Docker configuration for the environment, instead of porter you can use the base `docker-compose` utility that comes with Docker desktop. This requires these additional steps: + +- [Git installed](https://www.atlassian.com/git/tutorials/install-git) +- Use git to clone or download and extract the zip of the [REMS repository](https://github.com/mcode/REMS.git) - in your terminal navigate to the REMS repo folder. +- Before running, setup environment with VSAC credentials (see [setting environment variables section](#setting-environment-variables) for help) +- Add Compose Project Name to environment + +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. + +Set `COMPOSE_PROJECT_NAME` as a unique identifier in the .env file in the REMS Repository or in your terminal environment variables. + +- Start docker compose application + +```bash + cd REMS # Need to execute commands in directory with corresponding docker-compose.yml file located in the REMS repository + docker-compose up +``` +#### Docker Compose Cleanup + +##### Stop docker-compose and uninstall application +```bash + docker-compose down # Removes application servers +``` + +To remove all images, volumes, and artifacts set up during the install, run the following commands + +```bash + docker image prune -a + docker volume prune + docker network prune +``` + +##### Updating docker-compose application images + +```bash + docker-compose build --no-cache --pull [ ...] + docker-compose --force-recreate [ ...] +``` + +```bash + + # Options: + # --force-recreate Recreate containers even if their configuration and image haven't changed. + # --build Build images before starting containers. + # --pull Pull published images before building images. + # --no-cache Do not use cache when building the image. + # [ ...] Services to recreate, not specifying any service will rebuild and recreate all services +```