EndToEndSetupGuide.md

Local Developer Setup Guide (No Docker)

Follow this guide if you would like to start each application locally without using Docker. Each must be launched in a separate terminal window.

Table of Contents

• Local Developer Setup Guide (No Docker)
  • Table of Contents
  • Prerequisites
  • Clone each repository
  • Install nvm (Node Version Manager)
  • Utilities
    • keycloak
    • mongodb
  • Test Applications
    • test-ehr
    • request-generator
  • Core Applications
    • rems-admin
    • pims
    • rems-smart-on-fhir
    • rems-intermediary
• Verify the REMS Integration Prototype is working

Prerequisites

• Java, gradle
  • test-ehr
• Node
  • rems-admin, pims, rems-smart-on-fhir, request-generator
• nvm (Node Version Manager) (optional)
• git
  • On Windows 'Git Bash' was used for the command line interface

Clone each repository

1. Create a root directory for the REMS development work (we will call this <rems-root> for the remainder of this setup guide). While this step is not required, having a common root for the REMS Integration Prototype components will make things a lot easier down the line.

   mkdir rems-root

   rems-root will be the base directory into which all the other components will be installed. For example, test-ehr will be cloned to rems-root/test-ehr.

   Note: If you are using a different project structure from the above description, you will need to change the corresponding repo paths in docker-compose-dev.yml, docker-sync.yml, and docker-compose.yml

2. Now clone the REMS Integration Prototype component repositories from GitHub:

   cd rems-root
   
   git clone https://github.com/mcode/test-ehr.git
   git clone https://github.com/mcode/request-generator.git
   git clone https://github.com/mcode/rems-admin.git
   git clone https://github.com/mcode/pims.git
   git clone https://github.com/mcode/rems-smart-on-fhir.git
   git clone https://github.com/mcode/rems-setup.git
   git clone https://github.com/mcode/rems-intermediary.git

Install nvm (Node Version Manager)

• Using nvm makes switching Node versions easier, especially when working with projects that use other Node versions on your system.

  nvm install 20 # example of a default version
  nvm install 21 # another option

Utilities

keycloak

• Setup and run KeyCloak

  • Download KeyCloak 22.0.1 from www.github.com/keycloak/keycloak/releases/tag/22.0.1

    # Extract the downloaded file
    tar -xvf keycloak-22.0.1.tar.gz # Mac & Linux
    unzip <package.zip # Windows
    
    # Navigate into directory
    cd keycloak-22.0.1
    
    # Start Keycloak
    KEYCLOAK_ADMIN=admin KEYCLOAK_ADMIN_PASSWORD=admin ./bin/kc.sh start-dev --http-port=8180 --import-realm --hostname=localhost
    
    # Place realm file in proper folder
    mkdir data/import
    
    cp <test-ehr_location>/src/main/resources/ClientFhirServerRealm.json data/import/

  • Log in as admin user (optional)

    • Launch the admin page in a web browser localhost:8180/admin/
    • Select link for Administration Console
    • Log in as admin/admin

mongodb

• Setup and Run MongoDB

  • Download the latest version for your OS from www.mongodb.com/try/download/community

    # Extract the downloaded package
    tar -xvf <package.tgz> # Mac & Linux
    unzip <package.zip # Windows
    
    # Navigate into directory
    cd <package>
    
    # Create folder for database
    mkdir db
    
    # Run mongo
    ./bin/mongod --dbpath db

• Setup Mongo Shell mongosh to initialize the database

  • Download latest version for your OS from www.mongodb.com/try/download/shell

    # Extract the package
    tar -xvf <package.tgz> # Mac & Linux
    unzip <package.zip # Windows
    
    # Navigate into directory
    cd <package>
    
    # Initialize the database
    # NOTE: Database must already be running
    ./bin/mongosh mongodb://localhost:27017 <rems-root>/rems-setup/mongo-init.js

  • Alternate Install Instructions: www.mongodb.com/docs/mongodb-shell/install/#std-label-mdb-shell-install

• Restart mongo

  • Stop the application
  • Start as above

    ./bin/mongod --dbpath db

  • Applications should now be able to connect

Test Applications

test-ehr

• Terminal window 1

  # Navigate into directory already cloned from GitHub
  cd test-ehr
  
  # Run
  gradle bootRun

• Terminal window 2 (in the same directory)

  # Load Data
  gradle loadData

request-generator

# Navigate into directory already cloned from GitHub
cd request-generator

# Install dependencies
npm install

# Start the application
npm start

Core Applications

rems-admin

# Navigate into directory already cloned from GitHub
cd rems-admin

# Create a .env.local and set the VSAC_API_KEY variable to your VSAC key.
echo "VSAC_API_KEY=<your VSAC API key>" > .env.local

# Initialize Git submodules (REMS CDS Hooks)
git submodule update --init

# Install dependencies
npm install

# Start the application
npm start

pims

Terminal window 1: Backend

# Navigate to the backend directory
cd pims/backend

# Install dependencies
npm install

# Start the application
npm start

Terminal window 2: Frontend

# Navigate to the frontend directory
cd pims/backend

# Install dependencies
npm install

# Start the application
npm start

rems-smart-on-fhir

# Navigate into directory already cloned from GitHub
cd rems-smart-on-fhir

# Initialize Git submodules (REMS CDS Hooks)
git submodule update --init

# Install dependencies
npm install

# Start the application
npm start

rems-intermediary

# Navigate into directory already cloned from GitHub
cd rems-intermediary

# Initialize Git submodules (REMS CDS Hooks)
git submodule update --init

# Install dependencies
npm install

# Start the application
npm start

Verify the REMS Integration Prototype is working

See this guide to generate a test request.