[BI-2700] Improve Technical Documentation For DeltaBreed Paper

.env.template

@@ -1,22 +1,17 @@
-USER_ID=<user id of system user>
-GROUP_ID=<group id of system user>
-
-# Authentication variables
+##ORCID Authentication Variables for user to set
 OAUTH_CLIENT_ID=<oauth app client id>
-OAUTH_CLIENT_SECRET=<ouath_client_secret goes here>
-JWT_SECRET=<jwt secret goes here>
-JWT_DOMAIN=<jwt domain ex. localhost>
+OAUTH_CLIENT_SECRET=<oauth_client_secret goes here>
 
-# Database variables
-DB_PASSWORD=<database password goes here>
-DB_SERVER=<database server path (ex. localhost:5432)>
-DB_NAME=<database name>
-DB_USER=<database user>
-ADMIN_ORCID=<orcid for admin account goes here>
+##Variables already set
+#Authentication variables
+JWT_SECRET=insecure2520f59b2bccc64ce155482bc413f6b9ede5c6d418ab529d1b2051baa6f0849e
+JWT_DOMAIN=deltabreed.localhost
 
-# Build variables needed to pull down JAR files from Github Packages
-GITHUB_ACTOR=<github user name>
-GITHUB_TOKEN=<github personal access token>
+# Database variables
+DB_PASSWORD=postgres
+DB_SERVER=dbserver:5432
+DB_NAME=bidb
+DB_USER=postgres
 
 # Micronaut variables
 API_INTERNAL_PORT=8081
@@ -37,40 +32,50 @@ BRAPI_SERVER_PORT=8080
 BRAPI_DEFAULT_URL=http://brapiserver:8080
 BRAPI_REFERENCE_SOURCE=breedinginsight.org
 
-BRAPI_DB_SERVER=<brapi database server (ex. dbserver:5432)>
-BRAPI_DB=<brapi database name>
-BRAPI_DB_USER=<brapi database user>
-BRAPI_DB_PASSWORD=<brapi database password>
+#BrAPI database variables
+BRAPI_DB_SERVER=dbserver:5432
+BRAPI_DB=postgres
+BRAPI_DB_USER=postgres
+BRAPI_DB_PASSWORD=postgres
 
-WEB_BASE_URL=http://localhost
-API_BASE_URL=http://localhost
-ANALYTICS_GTAG_ID=<Google analytics gtag id>
+WEB_BASE_URL=http://deltabreed.localhost
+API_BASE_URL=http://deltabreed.localhost
 
 # Public domain name
-REGISTERED_DOMAIN=localhost
+REGISTERED_DOMAIN=deltabreed.localhost
 
 # Email relay information
-EMAIL_RELAY_HOST=<mailhog for development, email-smtp.us-east-1.amazonaws.com for production>
-EMAIL_RELAY_PORT=<1025 for development, 2587 for production>
-EMAIL_FROM=noreply@breedinginsight.org
-#EMAIL_RELAY_LOGIN=<blank for development>
-#EMAIL_RELAY_PASSWORD=<blank for development>
-
-REDIS_URL=<redis url, ex redis://localhost:6379>
-REDIS_TIMEOUT=<timeout, default 30s>
-REDIS_SSL=<enable ssl, default false>
-
-GIGWA_HOST=<gigwa host (including port), ex http://localhost:8080>
-GIGWA_USER=<username>
-GIGWA_PASSWORD=<password>
-GIGWA_MONGO_USER=<gigwa mongodb username>
-GIGWA_MONGO_PASSWORD=<gigwa mongodb password>
-
-AWS_REGION=<aws region, default us-east-1>
-AWS_ACCESS_KEY_ID=<access key>
-AWS_SECRET_KEY=<secret>
-AWS_GENO_BUCKET=<s3 bucket for genotypic data uploads>
-AWS_S3_ENDPOINT=<s3 endpoint, default https://s3.us-east-1.amazonaws.com
+EMAIL_RELAY_HOST=mailhog
+EMAIL_RELAY_PORT=1025
+EMAIL_FROM=bidevteam@cornell.edu
+
+REDIS_URL=redis://redis:6379
+
+GIGWA_PORT=6060
+GIGWA_HOST=http://gigwa:8080/
+GIGWA_USER=gigwadmin
+GIGWA_PASSWORD=nimda
+GIGWA_MONGO_USER=mongo
+GIGWA_MONGO_PASSWORD=mongo
+
+AWS_REGION=us-east-1
+AWS_ACCESS_KEY_ID=test
+AWS_SECRET_KEY=test
+#s3 bucket for genotypic data uploads
+AWS_GENO_BUCKET=breedinginsight.org-dev-bucket
+AWS_S3_ENDPOINT=http://localstack:4566
 
 # feature flags
 BRAPI_VENDOR_SUBMISSION_ENABLED=false # allow sample submissions to be transmitted to a vendor via BrAPI
+
+#Change if want to override defaults
+
+#REDIS_TIMEOUT=<timeout, default 30s>
+#REDIS_SSL=<enable ssl, default false>
+#USER_ID=<user id of system user, default 1001>
+#GROUP_ID=<group id of system user, default 1001>
+
+#Optional Variables
+#ANALYTICS_GTAG_ID=<Google analytics gtag id>
+#EMAIL_RELAY_LOGIN=
+#EMAIL_RELAY_PASSWORD=

README.md

@@ -6,43 +6,86 @@
     This repo contains the docker-compose configurations used to run DeltaBreed.
 </h2>
 
-# Prereqs
+# Table of Contents
+<p align="center">
+  <a href="#get_started">Getting Started</a> |
+  <a href="#architecture">Architecture</a> |
+  <a href="#other-envs">Setting Up Other Environments</a>
+</p>
+
+# <a id="get_started"></a>Getting Started
+## Outline
+<ul>
+<li>Download prereqs</li>
+<li>Set up OAuth with ORCID</li>
+<li>Set up environment variables</li>
+<li>Run docker-compose</li>
+<li>Get ORCID credentials into database</li>
+<li>Access DeltaBreed on web</li>
+</ul>
+
+## Download Prereqs
 Docker and Docker-compose are both required.
 
-# Architecture
+## Set up OAuth with ORCID
+Running DeltaBreed requires setting up OAuth with [ORCID](https://info.orcid.org/what-is-orcid/) (Open Researcher and Contributor ID).
+
+<ol>
+<li><a href="https://orcid.org/register">Create an ORCID account</a></li>
+<li>Sign into ORCID</li>
+<li>Go to "Developer Tools"</li>
+<li>Agree to Terms of Service and register for ORCID public API credentials</li>
+<li>Enter application name and description (no particular requirements)</li>
+<li>Enter application URL <code>http://deltabreed.localhost:8080</code></li>
+<li>Add Redirect URI <code>http://deltabreed.localhost/sso/success/orcid</code></li>
+<li>Select "Save application" at the bottom of the page</li>
+<li>Copy the generated Client ID and Client Secret to add to the .env file (see <a href="env_vars">Set up environment variables</a>)</li>
+</ol>
+
+## <a id="env_vars"></a>Set up environment variables
+To set necessary private environment variables for DeltaBreed to run, at the root level of the repo locally create a file called `.env`. 
+A template exists named `.env.template` that has most environment variables already filled. 
+
+In this new `.env` based off the template, set `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` to the generated Client ID and Client Secret copied in the previous step
+
+## Run docker-compose
+Run the following in the bi-docker-stack repository
+
+```
+docker-compose -f docker-compose.yml -f docker-compose-redis.yml -f docker-compose-gigwa.yml -f docker-compose-localstack.yml -f docker-compose-mailhog.yml -f docker-compose-qa.yml up -d --build
+```
+
+## Get ORCID credentials into database
+To get ORCID credentials into the database, an interactive script must be run that prompts the user to input their ORCID and email.
+
+For Mac/Linux, run `addUser.sh`
+
+For Windows, run `addUser.ps1`
+
+## Access DeltaBreed on web
+DeltaBreed can then be accessed via `http://deltabreed.localhost:8080`. 
+
+# <a id="architecture"></a> Architecture
 The primary components of DeltaBreed are the Web UI (Breeding-Insight/bi-web) and the API (Breeding-Insight/bi-api).
 The [BrAPI Java Server](https://github.com/plantbreeding/brapi-Java-TestServer) is used for phenotypic data storage, [Gigwa](https://github.com/SouthGreenPlatform/Gigwa2) is used for genotypic data storage, and interoperability with external applications such as [Field Book](https://github.com/PhenoApps/Field-Book/) is enabled by [BrAPI](https://brapi.org/).
 DeltaBreed uses [ORCID](https://orcid.org/) for authentication.
 
 ![DeltaBreed v1.0 architecture diagram.](./images/architecture.1.0.png)
 
-# Configuration
-The containers are not run by the root user but by a new user and group called
-'host'.  The user and group ids for host are both set to 1001 by default.  If
-you wish to change these to your own user and group ids, add the following
-contents to .env:
-```
-USER_ID=1001
-GROUP_ID=1001
-```
-Change 1001 to your own id values.  You can find at the console your user and group ids using the id command:
-for user id
-```
-id -u
-```
-and for group id
+# <a id="other_envs"></a>Setting up Other Environments
+## Development Environment
+
+To run a development environment, you will need to initialize the git submodules that exist within this repository:
+
 ```
-id -g
+git submodule update --init --recursive
 ```
 
-## Configure Services
-
-Private values used in each environment are stored in Lastpass and are never
-placed in docker-compose.yml and never committed to the repo.  At the root level
-of the repo locally create a file called `.env` (a template exists named `.env.template`) 
-and save the Lastpass contents for "bi-api secrets" in this file.
+Then run:
 
-# Run
+```
+docker-compose -f docker-compose.yml -f docker-compose-redis.yml -f docker-compose-gigwa.yml -f docker-compose-dev.yml up -d
+```
 
 ## Production Environment
 
@@ -104,17 +147,21 @@ traffic to the appropriate upstream server. Any new features added to bi-api
 that use an endpoint not in the /v1/ or /sso/ name spaces must have a rule added
 to the proxy config in order to send these requests upstream.
 
-
-# Development Environment
-
-To run a development environment, you will need to initialize the git submodules that exist within this repository:
-
+## User Configuration
+The containers are not run by the root user but by a new user and group called
+'host'.  The user and group ids for host are both set to 1001 by default.  If
+you wish to change these to your own user and group ids, add the following
+contents to .env:
 ```
-git submodule update --init --recursive
+USER_ID=1001
+GROUP_ID=1001
 ```
-
-Then run:
-
+Change 1001 to your own id values.  You can find at the console your user and group ids using the id command:
+for user id
 ```
-docker-compose -f docker-compose.yml -f docker-compose-redis.yml -f docker-compose-gigwa.yml -f docker-compose-dev.yml up -d
+id -u
 ```
+and for group id
+```
+id -g
+```

addUser.ps1

@@ -0,0 +1,8 @@
+$oauth_id = Read-Host "Enter ORCID (e.g. 0000-1111-2222-3333)"
+$email = Read-Host "Enter email (must be the email used with ORCID)"
+
+$insertUser = "INSERT INTO bi_user (orcid, name, email, created_by, updated_by, active) VALUES ('${oauth_id}', 'admin', '${email}', '00000000-0000-0000-0000-000000000000', '00000000-0000-0000-0000-000000000000', true);"
+$insertRole = "INSERT INTO system_user_role (bi_user_id, system_role_id, created_by, updated_by) VALUES ((SELECT id FROM bi_user WHERE email='${email}'), (SELECT id FROM system_role WHERE domain = 'System Administrator'), '00000000-0000-0000-0000-000000000000', '00000000-0000-0000-0000-000000000000');"
+
+docker exec -it bidb psql -U postgres -d bidb -c $insertUser
+docker exec -it bidb psql -U postgres -d bidb -c $insertRole

addUser.sh

@@ -0,0 +1,8 @@
+read -p "Enter ORCID (e.g. 0000-1111-2222-3333):" oauth_id
+read -p "Enter email (must be the email used with ORCID):" email
+
+insertUser="INSERT INTO bi_user (orcid, name, email, created_by, updated_by, active) VALUES ('${oauth_id}', 'admin', '${email}', '00000000-0000-0000-0000-000000000000', '00000000-0000-0000-0000-000000000000', true);"
+docker exec -it bidb psql -U postgres -d bidb -c "${insertUser}"
+
+insertRole="INSERT INTO system_user_role (bi_user_id, system_role_id, created_by, updated_by) VALUES ((SELECT id FROM bi_user WHERE email='${email}'), (SELECT id FROM system_role WHERE domain = 'System Administrator'), '00000000-0000-0000-0000-000000000000', '00000000-0000-0000-0000-000000000000');"
+docker exec -it bidb psql -U postgres -d bidb -c "${insertRole}"

docker-compose-localstack.yml

@@ -6,6 +6,7 @@ services:
     image: localstack/localstack:3.0.2
     ports:
       - "4566:4566"
+    restart: always
     networks:
       backend:
         aliases:

docker-compose-mailhog.yml

@@ -0,0 +1,12 @@
+version: "3.7"
+
+services:
+  mailhog:
+    image: mailhog/mailhog:latest
+    container_name: mailhog
+    restart: always
+    ports:
+      - ${MAILHOG_WEB_PORT:-8025}:8025
+      - ${MAILHOG_PORT:-1025}:1025
+    networks:
+      backend: