From 14e113cd2817836adde87aaf436accbc9104b103 Mon Sep 17 00:00:00 2001 From: Ariel Rotter-Aboyoun Date: Tue, 29 Oct 2024 08:30:30 -0700 Subject: [PATCH] Update with the confluence information --- README.md | 9 ++-- angular/README.md | 35 +++++++++---- api/README.md | 131 ++++++++++++++++++++++++++++++---------------- 3 files changed, 115 insertions(+), 60 deletions(-) diff --git a/README.md b/README.md index b0090b9b5..3b0a867e2 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -![API tests](https://github.com/bcgov/NRPTI/workflows/API%20tests/badge.svg) ![Front-End tests](https://github.com/bcgov/NRPTI/workflows/Front-End%20tests/badge.svg) - # NRPTI Natural Resources Public Transparency Initiative monorepo. This supports the LNG Regulatory interface, Natural Resource Compliance and Enforcement Database, and soon the BC Mines Information site. @@ -20,10 +18,11 @@ All documents uploaded to the NRPTI system are first checked by the ClamAV anti- # Running it locally -**IMPORTANT:** Please read through this confluence page before running anything. -https://apps.nrs.gov.bc.ca/int/confluence/pages/viewpage.action?pageId=208740091 +To run NRPTI locally, run the `api/` subdirectory and then the `angular/` subdirectory. See [api/README.md](api/README.md) for instructions to begin the process. + +If you already have the API running, see [angular/README.md](angular/README.md) for instructions to run the frontend. -See the READMEs in the `angular/` and `api/` subdirectories for further instructions. +_Note: NRPTI Does not work in Firefox. Please use Safari or Chrome._ # VSCode Extensions diff --git a/angular/README.md b/angular/README.md index acbf50762..c46765be3 100644 --- a/angular/README.md +++ b/angular/README.md @@ -2,11 +2,11 @@ Angular front-ends for the Natural Resources Public Transparency Interface (NRPTI) application. -- [admin-nrpti](https://github.com/bcgov/nrpti/angular/projects/admin-nrpti) - front-end for nrced admin users. -- [public-nrced](https://github.com/bcgov/nrpti/angular/projects/public-nrpti) - front-end for nrced public users. -- [public-lng](https://github.com/bcgov/nrpti/angular/projects/public-lng) - front-end for lng public users. -- [common](https://github.com/bcgov/nrpti/angular/projects/common) - common components for NRPTI front-end sites. -- [global](https://github.com/bcgov/nrpti/angular/projects/global) - global components for angular front-end sites. +- [admin-nrpti](projects/admin-nrpti) - front-end for nrced admin users. +- [public-nrced](projects/public-nrpti) - front-end for nrced public users. +- [public-lng](projects/public-lng) - front-end for lng public users. +- [common](projects/common) - common components for NRPTI front-end sites. +- [global](projects/global) - global components for angular front-end sites. # Prerequisites @@ -16,13 +16,15 @@ Angular front-ends for the Natural Resources Public Transparency Interface (NRPT | npm | latest | https://www.npmjs.com/ | Node Package Manager | | ng | 7.x.x | https://cli.angular.io/ | Angular CLI | -_Note: Node 14.21.3 is highly recommended._ +_NOTE: Although NRPTI uses Node 10 on OpenShift, this guide will instruct you to use Node 14.21.3. This has been the most successful for installing and running NRPTI locally._ -_Note: This app also requires [`bcgov/nrpti/api`](https://github.com/bcgov/NRPTI/tree/master/api) to handle its requests and authentication._ +_Note: This app also requires [`bcgov/nrpti/api`](../api) to handle its requests and authentication. If you haven't already, please follow the README in that folder to get the API running._ -## Install [Node + NPM](https://nodejs.org/en/) +_Note: NRPTI Does not work in Firefox. Please use Safari or Chrome._ -_Note: NVM can be used to install and manage multiple versions of NodeJS and npm ([Windows version]((https://github.com/coreybutler/nvm-windows)), [Unix / Linux / macOS version](https://github.com/nvm-sh/nvm))._ +## Install [Node](https://nodejs.org/download/release/latest-v14.x/) + +_Note: NVM can be used to install and manage multiple versions of NodeJS and npm ([Windows version]((https://github.com/coreybutler/nvm-windows)), [Unix / Linux / macOS version](https://github.com/nvm-sh/nvm)). It's highly recommended to use NVM when working on this project._ ## Install [Angular CLI](https://cli.angular.io/) @@ -50,10 +52,11 @@ During development, a library can be built and symlinked instead of published. T # Build and Run -0. Downgrade your node version +0. Use Python 2.7 and Node 14! ``` - nvm use + nvm use 14.21.3 + pyenv global 2.7 ``` 1. Download dependencies @@ -61,6 +64,10 @@ During development, a library can be built and symlinked instead of published. T ``` npm install ``` + _NOTE FOR WINDOWS INSTALL: if you are using pyenv and still getting errors related to python2 or node-sass, run this command to set the python2 path in the npm config :_ + ``` + npm config set python "C:\path\to\python.exe" + ``` 2. Build library/symlink @@ -80,6 +87,8 @@ During development, a library can be built and symlinked instead of published. T _Note: This will run all angular applications in parallel, in the same console._ + _Note: Remember to use Safari or Chrome._ + # Linting and Formatting ## Info @@ -101,6 +110,8 @@ Recommend installing the [VSCode Prettier extension](https://github.com/prettier ## Run Linters + Formatters + Auto Fix +_Note: In the worst case scenario, where linting/formatting has been neglected, then these `lint-fix` commands have the potential to create 100's of file changes. In this case, it is recommended to only run these commands as part of a separate commit._ + _Note: Not all linting/formatting errors can be automatically fixed, and will require human intervention._ - Run all linters and fix all problems, in series @@ -114,6 +125,7 @@ _Note: Not all linting/formatting errors can be automatically fixed, and will re ``` npm run lint:ts ``` +_Note: Remember to use Node 14 when running the linter! Newer versions will error._ # Testing @@ -144,6 +156,7 @@ When viewing test output in the browser, via localhost:9876, Firefox produces so ``` npm run test-ci ``` +_Note: Remember to use Node 14 when running tests! Newer versions will error._ # Code Scaffolding Using Angular CLI diff --git a/api/README.md b/api/README.md index c23ae17cd..98dd463ff 100644 --- a/api/README.md +++ b/api/README.md @@ -2,51 +2,92 @@ API for the Natural Resources Public Transparency Interface (NRPTI). -* [api](https://github.com/bcgov/nrpti/api) - back-end that serves all admin and public requests. +* [api](../api) - back-end that serves all admin and public requests. -# Running with Docker - -Run using the command `docker-compose up` to begin building and running the `api` - -# Running Locally without Docker +# Requirements | Technology | Version | Website | Description | |------------|-----------------|---------------------------------------------|-------------------------------------------| | node | 10.x.x - 14.x.x | https://nodejs.org/en/ | JavaScript Runtime | | npm | latest | https://www.npmjs.com/ | Node Package Manager | -| yarn | latest | https://yarnpkg.com/en/ | Package Manager (more efficient than npm) | -| mongodb | 3.4 - 3.6 | https://docs.mongodb.com/v3.6/installation/ | NoSQL database | +| mongodb | 3.6 | https://docs.mongodb.com/v3.6/installation/ | NoSQL database | +| pyenv | latest | Homebrew (Mac) or pip (Windows) | Python version manager | + +_NOTE: Although NRPTI uses Node 10 on OpenShift, this guide will instruct you to use Node 14.21.3. This has been the most successful for installing and running NRPTI locally._ -_Note: Node 14.21.3 is highly recommended._ +# Optional + +| Technology | Version | Website | Description | +|------------|-----------------|---------------------------------------------|-------------------------------------------| +| docker | latest | https://docs.docker.com/engine/install/ | Containerisation platform | + +# Running Locally ## Install [NodeJS](https://nodejs.org/download/release/latest-v14.x/) -_Note: NVM can be used to install and manage multiple versions of NodeJS and npm ([Windows version]((https://github.com/coreybutler/nvm-windows)), [Unix / Linux / macOS version](https://github.com/nvm-sh/nvm))._ +_Note: NVM can be used to install and manage multiple versions of NodeJS and npm ([Windows version]((https://github.com/coreybutler/nvm-windows)), [Unix / Linux / macOS version](https://github.com/nvm-sh/nvm)). It's highly recommended to use NVM when working on this project._ + +## Install Pyenv +#### On Mac: +``` +brew install pyenv +``` +#### On Windows: +``` +pip install pyenv-win +``` ## Install [MongoDB](https://docs.mongodb.com/v3.6/installation/) # Build and Run +0. Use Python 2.7 and Node 14! + + ``` + nvm use 14.21.3 + pyenv global 2.7 + ``` 1. Download dependencies -``` -npm install -``` + + ``` + npm install + ``` + _NOTE FOR WINDOWS INSTALL: if you are using pyenv and still getting errors related to python2 or node-sass, run this command to set the python2 path in the npm config :_ + ``` + npm config set python "C:\path\to\python.exe" + ``` + 2. Start MongoDB -``` -brew services start mongodb-community@3.6 -``` + + #### With Docker: + ``` + cd ../ + docker-compose up mongo + cd api + ``` + #### Without Docker: + ``` + brew services start mongodb-community@3.6 + ``` + 3. Run the migrations locally -``` -db-migrate up -e local -``` -> _Note: you may need to adjust Minio env variables, or skip the loadMemDocs migration_ + + ``` + db-migrate up -e local + ``` + _Note: you may need to adjust Minio env variables, or delete the loadMemDocs migration._ + 4. Run the app -``` -npm start -``` -5. Go to http://localhost:3000/api/docs to verify that the application is running. ->_Note: To change the default port edit `swagger.yaml`._ + ``` + npm start + ``` + +5. Open http://localhost:3000/api/docs in Safari or Chrome to verify that the application is running. + + _Note: To change the default port edit `swagger.yaml`._ + +To continue local set-up with the front-end, see [bcgoc/angular/README.md](../angular/README.md). # Linting and Formatting @@ -65,24 +106,24 @@ These 2 linters (tslint, Prettier) do have overlapping rules. To avoid weird ru * ESlint: eslint.json * Prettier: .prettierrc .prettierignore -## Run Linters - -* Lint the `*.js` files using `ESLint`. -``` -npm run lint -``` - -## Run Linters + Formatters +## Run Linters + Formatters + Auto Fix _Note: In the worst case scenario, where linting/formatting has been neglected, then these `lint-fix` commands have the potential to create 100's of file changes. In this case, it is recommended to only run these commands as part of a separate commit._ _Note: Not all linting/formatting errors can be automatically fixed, and will require human intervention._ -* Lint and fix the `*.js` files using `ESLint` + `Prettier`. +- Lint the `*.js` files using `ESLint`. -``` -npm run lint-fix -``` + ``` + npm run lint + ``` + +- Lint and fix the `*.js` files using `ESLint` + `Prettier`. + + ``` + npm run lint-fix + ``` +_Note: Remember to use Node 14 when running the linter! Newer versions will error._ # API Specification @@ -140,15 +181,17 @@ This project contains two kinds of unit tests. Regular unit tests and API unit * Run the unit and api tests. * Note: the `package.json` `tests` command sets the `UPLOAD_DIRECTORY` environment variable, the command for which may be OS specific and therefore may need adjusting depending on your machines OS. -``` -npm run test -``` + ``` + npm run test + ``` -Run individual test suites using the relative command. For example: +* Run individual test suites using the relative command. For example: -``` -npm run test api/src/importers/alc/base-record-utils.test.js -``` + ``` + npm run test api/src/importers/alc/base-record-utils.test.js + ``` + +_Note: Remember to use Node 14 when running tests! Newer versions will error._ ## API Tests