From 36970ae68e6165268a84dcc184ab455c17765dac Mon Sep 17 00:00:00 2001 From: Jackie Quach Date: Wed, 31 Jul 2024 15:44:21 -0400 Subject: [PATCH 1/2] update local dev section of readme --- .env.sample | 12 +++++++++-- CHANGELOG.md | 2 +- README.md | 55 ++++++++++++++++++++++++++++++++++------------- package-lock.json | 18 ---------------- package.json | 1 - 5 files changed, 51 insertions(+), 37 deletions(-) diff --git a/.env.sample b/.env.sample index bcf8445f..e4c5c117 100644 --- a/.env.sample +++ b/.env.sample @@ -9,11 +9,19 @@ API_URL=http://drb-api-qa.nypl.org # https://github.com/NYPL-Simplified/web-reader#cors-proxy NEXT_PUBLIC_PROXY_URL=http://localhost:3001/?requestUrl= + +# OPTIONAL LOCAL VARIABLES + # READER VERSION NEXT_PUBLIC_READER_VERSION="v2" # Airtable API Key # The airtable key is only needed in development if the developer needs to send data via the feedback form. - NEXT_PUBLIC_AIRTABLE_API_KEY=[insert key here] -NEXT_PUBLIC_ADOBE_ANALYTICS=[insert AA url here] \ No newline at end of file + +# ADOBE ANALYTICS +NEXT_PUBLIC_ADOBE_ANALYTICS=[insert AA url here] + +# NEW RELIC +NEW_RELIC_APP_NAME=[insert name here] +NEW_RELIC_LICENSE_KEY=[insert key here] \ No newline at end of file diff --git a/CHANGELOG.md b/CHANGELOG.md index 77ff3ced..60b11040 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,7 +10,7 @@ - Add error page for /read links with invalid source - Implement "Read Online" for UP items - SFR-2032: Update local API url - +- Update README with instructions to run app locally ## [0.18.1] diff --git a/README.md b/README.md index 3597b99a..3da38f8d 100644 --- a/README.md +++ b/README.md @@ -1,50 +1,75 @@ -## NYPL ResearchNow - -### ResearchNow Search & Retrieval Application +# Digital Research Books Frontend [![GitHub version](https://badge.fury.io/gh/NYPL%2Fsfr-bookfinder-front-end.svg)](https://badge.fury.io/gh/NYPL%2Fsfr-bookfinder-front-end) -Digital Research Books' front end application based on NYPL's React Design System. +Digital Research Books' front end application based on NYPL's Reservoir Design System. Provides a "Welcome page" entry point with heading, search box, and tagline. Connects to an ElasticSearch index via an API endpoint (https://digital-research-books-api.nypl.org). Simple searches can be entered in the form and an index response is displayed back to the user. -### Requirements +## Requirements This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). -### Contributing: Local Development +## Contributing: Local Development + +### Getting Started + +#### Prerequisites -Clone the repo and run `npm install`. +- Node.js (v18 or later) +- To view pdfs locally through the webreader, you will need to set up a local proxy. If you used environment variables from `.env.sample` you should be able to pull the [web-reader](https://github.com/NYPL-Simplified/web-reader) repo, install it, and run `npm run cors-proxy`. See the web-reader repo for more [instructions](https://github.com/NYPL-Simplified/web-reader#cors-proxy) -Create a `.env` file and add the `APP_ENV` and `API_URL`. See `.env.sample` for an example. +1. Install the required packages -Run `npm run dev` to start the local server at `localhost:3000` +``` +npm install +``` + +2. Create a `.env` file and add required environment variables. See `.env.sample` for an example. + +### Running the app locally with npm at `localhost:3000` + +``` +npm run dev +``` -To view pdfs locally through the webreader, you will need to set up a local proxy. If you used environment variables from `.env.sample` you should be able to pull the [web-reader](https://github.com/NYPL-Simplified/web-reader) repo, install it, and run `npm run cors-proxy`. See the web-reader repo for more [instructions](https://github.com/NYPL-Simplified/web-reader#cors-proxy) +### Local Hosting In order to successfully login under a local deployment, you will need to update your machine's `etc/hosts` file. This hosts file maps local host names to ip addresses. -Add this to your `etc/hosts` file: +This is necessary because NYPL's authentication system works by reading cookies and parsing the patron's encrypted credentials. These cookies only work on .nypl.org domains, so we need to map our local deployment to a .nypl.org domain. + +Add this line to your `etc/hosts` file: ``` 127.0.0.1 local.nypl.org ``` +### Running the app locally with Docker + +1. Download and install Docker. +2. `cd` into `sfr-bookfinder-front-end` repo +3. To build and run the application, run: + +``` +docker-compose up +``` + +4. Check that app is being served at http://localhost:3000 + ### Deploying to Production -1. Create a new branch off `development` with the name `NO-REF_prepare-`, i.e. `NO-REF_prepare-1.2.3`. Replace any reference to "Pre-release" and the previous production version in the package.json and package-lock.json files with the current version number. Push the branch and create a Pull Request with the name `NOREF prepare release`, i.e. `NOREF prepare 1.2.3 release`. Merge these changes once the PR is approved. +1. Create a new branch off `development` with the name `NO-REF_prepare-`, i.e. `NO-REF_prepare-1.2.3`. Replace any reference to "Pre-release" and the previous production version in the package.json and package-lock.json files with the current version number. Push the branch and create a Pull Request with the name `NOREF prepare release`, i.e. `NOREF prepare 1.2.3 release`. Merge these changes once the PR is approved. 2. Create a Pull Request to `production` from `development` with the name `Release to production`, i.e. `Release 1.2.3 to production`. The description of the PR should be the new version's changelog to be used in the tag and release step of the .yaml file. 3. Merge the PR after approval to trigger the [`build-production.yaml`](./.github/workflows/build-production.yaml) GitHub Action, which pushes a Docker image to ECR, updates the `production` ECS deployment, and creates a new release version on GitHub. 4. Add the link to the PR to the release ticket in Jira and tag the appropriate member of QA, the project manager, and the product manager. Move the ticket to "In QA" and assign it to the appropriate member of QA. QA should be done on https://drb-qa.nypl.org/. - ### Dependencies - NextJS -- Redux -- NYPL Header and Footer npm modules - NYPL Design System +- NYPL Web Reader ### Usage diff --git a/package-lock.json b/package-lock.json index 5c2fa50f..5a4b3253 100644 --- a/package-lock.json +++ b/package-lock.json @@ -23,7 +23,6 @@ "next-transpile-modules": "^7.0.0", "react": "^18.2.0", "react-cookie": "7.1.4", - "redux": "4.0.1", "sass": "^1.62.1", "typescript": "^4.1.3" }, @@ -20913,15 +20912,6 @@ "node": ">=8" } }, - "node_modules/redux": { - "version": "4.0.1", - "resolved": "https://registry.npmjs.org/redux/-/redux-4.0.1.tgz", - "integrity": "sha512-R7bAtSkk7nY6O/OYMVR9RiBI+XghjF9rlbl5806HJbQph0LJVHZrU5oaO4q70eUKiqMRqm4y07KLTlMZ2BlVmg==", - "dependencies": { - "loose-envify": "^1.4.0", - "symbol-observable": "^1.2.0" - } - }, "node_modules/reflect-metadata": { "version": "0.1.13", "resolved": "https://registry.npmjs.org/reflect-metadata/-/reflect-metadata-0.1.13.tgz", @@ -22647,14 +22637,6 @@ "react": "^16.11.0 || ^17.0.0 || ^18.0.0" } }, - "node_modules/symbol-observable": { - "version": "1.2.0", - "resolved": "https://registry.npmjs.org/symbol-observable/-/symbol-observable-1.2.0.tgz", - "integrity": "sha512-e900nM8RRtGhlV36KGEU9k65K3mPb1WV70OdjfxlG2EAuM1noi/E/BaW/uMhL7bPEssK8QV57vN3esixjUvcXQ==", - "engines": { - "node": ">=0.10.0" - } - }, "node_modules/symbol-tree": { "version": "3.2.4", "resolved": "https://registry.npmjs.org/symbol-tree/-/symbol-tree-3.2.4.tgz", diff --git a/package.json b/package.json index 32d15646..7535cd5e 100644 --- a/package.json +++ b/package.json @@ -29,7 +29,6 @@ "next-transpile-modules": "^7.0.0", "react": "^18.2.0", "react-cookie": "7.1.4", - "redux": "4.0.1", "sass": "^1.62.1", "typescript": "^4.1.3" }, From 8a39ae3e96dcf604bf4cfe4f04de8b41c5bbb020 Mon Sep 17 00:00:00 2001 From: Jackie Quach Date: Thu, 1 Aug 2024 15:05:43 -0400 Subject: [PATCH 2/2] address comments and update heading levels --- .env.sample | 2 +- README.md | 26 +++++++++++++------------- 2 files changed, 14 insertions(+), 14 deletions(-) diff --git a/.env.sample b/.env.sample index e4c5c117..b94074f2 100644 --- a/.env.sample +++ b/.env.sample @@ -24,4 +24,4 @@ NEXT_PUBLIC_ADOBE_ANALYTICS=[insert AA url here] # NEW RELIC NEW_RELIC_APP_NAME=[insert name here] -NEW_RELIC_LICENSE_KEY=[insert key here] \ No newline at end of file +NEW_RELIC_LICENSE_KEY=[insert key here] diff --git a/README.md b/README.md index 3da38f8d..6e10fefc 100644 --- a/README.md +++ b/README.md @@ -7,17 +7,17 @@ Digital Research Books' front end application based on NYPL's Reservoir Design S Provides a "Welcome page" entry point with heading, search box, and tagline. Connects to an ElasticSearch index via an API endpoint (https://digital-research-books-api.nypl.org). Simple searches can be entered in the form and an index response is displayed back to the user. -## Requirements +### Requirements This is a [Next.js](https://nextjs.org/) project bootstrapped with [`create-next-app`](https://github.com/vercel/next.js/tree/canary/packages/create-next-app). -## Contributing: Local Development +### Contributing: Local Development -### Getting Started +#### Getting Started -#### Prerequisites +##### Prerequisites -- Node.js (v18 or later) +- Install Node.js v18 or later - To view pdfs locally through the webreader, you will need to set up a local proxy. If you used environment variables from `.env.sample` you should be able to pull the [web-reader](https://github.com/NYPL-Simplified/web-reader) repo, install it, and run `npm run cors-proxy`. See the web-reader repo for more [instructions](https://github.com/NYPL-Simplified/web-reader#cors-proxy) 1. Install the required packages @@ -28,13 +28,13 @@ npm install 2. Create a `.env` file and add required environment variables. See `.env.sample` for an example. -### Running the app locally with npm at `localhost:3000` +#### Running the app locally with npm at `localhost:3000` ``` npm run dev ``` -### Local Hosting +#### Local Hosting In order to successfully login under a local deployment, you will need to update your machine's `etc/hosts` file. This hosts file maps local host names to ip addresses. @@ -46,7 +46,7 @@ Add this line to your `etc/hosts` file: 127.0.0.1 local.nypl.org ``` -### Running the app locally with Docker +#### Running the app locally with Docker 1. Download and install Docker. 2. `cd` into `sfr-bookfinder-front-end` repo @@ -73,7 +73,7 @@ docker-compose up ### Usage -### Searchbar +#### Searchbar Currently takes in a query string to pass along to the ResearchNow Search API which submits a keyword search to the Elasticsearch instance, and renders the returned output. Sends the `query` parameter specified in the rendered search form on the main page. @@ -88,23 +88,23 @@ Term combinations These types of combinations can be used with any available field selection. -### Filtering +#### Filtering Search Results can be filtered by year range, language and available format. -### Advanced Search +#### Advanced Search Advanced Search works like the Simple Search, but allows searching for multiple fields and for pre-filtering. Terms use the AND boolean operator Term combinations - Example: Subject:"English Literature" AND Keyword:"Witches" -### Works and Editions +#### Works and Editions - Each source record is represented as an Item (something that can actually be read online), which are grouped into Editions (e.g. the 1917 edition of X), which are in turn grouped into Works, (e.g. Moby Dick, or, The Whale). Through this a user can search for and find a single Work record and see all editions of that Work and all of its options for reading online. - The information and code for this normalization is found in the [drb-etl-pipeline repo](https://github.com/NYPL/drb-etl-pipeline) -### Accessing books +#### Accessing books - Books can be read three ways: - Embedded page: DRB embeds a read-online page from a different source. DRB commonly does this for Hathitrust books