From ec84fca9edacbfc9edfe7dbb61661a8d5e53100b Mon Sep 17 00:00:00 2001 From: William Welling <8352733+wwelling@users.noreply.github.com> Date: Thu, 25 Aug 2022 10:37:43 -0500 Subject: [PATCH] Tech debt weaver upgrade (#443) * add pr and issue templates * Update .gitignore based on new designs. Use the triple pound symbol as section separators. Organized in this order: 1) Section 1.1) Hidden Directories 1.2) Directories 1.3) Hidden Files 1.4) Files 1.5) Inverse rules (same hidden to directory to file pattern is repeated for these). * Update readme and related files. This brings in the newer practices (which have not yet fully been ironed out yet). An attempt is made to merge the existing documentation with this. There may be additional changes once this processed is ironed out. * Add Maven instructions and do some clean up. - The deployment should also explain Maven. - Remove or replace stale MAGPIE references. - Don't include explicit bold in header titles. * Standardize LICENSE and update the date. The license is derived from https://mit-license.org/ . * Upgrade parent project to Weaver-Webservice-Core 2.1.1-RC11. * Clean up log files of not being used and ensure used log files are accurate and consistent. * Update Dockerfile for consistency and related. - Update Dockerfile for consistency. - Update Dockerfile to combine RUN commands for better layer caching. - Update Dockerfile to use --non-unique to both useradd and groupadd commands. - Update Dockerfile RUN build command to utilize jar profile. - Refactor NPM_REGISTRY_URL to NPM_REGISTRY as not an actual URL. * Should have a docker-compose.yml with .env similar to app repos * Update GitHub workflow step. * Update karma.conf.js for consistency and related. - Update karma.config.js for consistency. - Update karma.config.js preprocessors to include index.html app/**/*.html. - Update karma.config.js using single quotes. * Do not have git ignore the build/ directory. * Remove version and any references from appConfig.js.template. * Be consistent with trailing commas. * Add Missing node/npm files to .gitignore. * Update .gitignore. * Update readme, adding notes and additional links. There is a user documentation wiki, so point to that. Only reference the additional settings found in the deploying file. * Update the deploying document with a more correct example. * Siwtch to 2.x branch for weaver-ui workflow. Co-authored-by: Kevin Day Co-authored-by: Kevin Day <35114839+kaladay@users.noreply.github.com> --- .github/ISSUE_TEMPLATE/bug_report.md | 37 +++ .github/ISSUE_TEMPLATE/feature_request.md | 19 ++ .github/pull_request_template.md | 37 +++ .github/workflows/build.yml | 16 +- .gitignore | 114 +++++++-- CONTRIBUTING.md | 87 +++---- DEPLOYING.md | 290 ++++++++++++++++------ Dockerfile | 88 +++---- LICENSE | 23 +- README.md | 88 +++++-- build/appConfig.js.template | 2 - docker-compose.yml | 4 +- example.env | 7 +- karma.conf.js | 144 +++++------ pom.xml | 2 +- src/test/resources/logback-test.xml | 3 +- 16 files changed, 629 insertions(+), 332 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/pull_request_template.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 00000000..ad553f49 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,37 @@ +--- +name: Bug report +about: Create a report to help us improve +title: '' +labels: '' + +--- + +**Describe the bug** +A clear and concise description of what the bug is. + +**To Reproduce** +Steps to reproduce the behavior: +1. Go to '...' +2. Click on '....' +3. Scroll down to '....' +4. See error + +**Expected behavior** +A clear and concise description of what you expected to happen. + +**Screenshots** +If applicable, add screenshots to help explain your problem. + +**Desktop (please complete the following information):** + - OS: [e.g. iOS] + - Browser [e.g. chrome, safari] + - Version [e.g. 22] + +**Smartphone (please complete the following information):** + - Device: [e.g. iPhone6] + - OS: [e.g. iOS8.1] + - Browser [e.g. stock browser, safari] + - Version [e.g. 22] + +**Additional context** +Add any other context about the problem here. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 00000000..a27874f1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,19 @@ +--- +name: Feature request +about: Suggest an idea for this project +title: '' +labels: '' + +--- + +**Is your feature request related to a problem? Please describe.** +A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] + +**Describe the solution you'd like** +A clear and concise description of what you want to happen. + +**Describe alternatives you've considered** +A clear and concise description of any alternative solutions or features you've considered. + +**Additional context** +Add any other context or screenshots about the feature request here. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 00000000..8575e3b0 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,37 @@ +# Description + +Please include a summary of the changes and the related issue. Please also include relevant motivation and context. List any dependencies that are required for this change. + +Fixes # (issue) + +## Type of change + +Please delete options that are not relevant. + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] This change requires a documentation update + +# How Has This Been Tested? + +Please describe the tests that you ran to verify your changes. Provide instructions so we can reproduce. Please also list any relevant details for your test configuration + +- [ ] Test A +- [ ] Test B + +**Test Configuration**: +* Toolchain: +* SDK: + +# Checklist: + +- [ ] My code follows the style guidelines of this project +- [ ] I have performed a self-review of my code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] I have made corresponding changes to the documentation +- [ ] My changes generate no new warnings +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] Any dependent changes have been merged and published in downstream modules + diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index e127dafc..2c0ff87d 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -17,7 +17,7 @@ jobs: with: repository: TAMULib/Weaver-UI-Core path: weaver-ui - ref: 2.x-staging + ref: 2.x - name: "Run Weaver-UI-Core Docker Compose Registry Image" run: docker-compose -f $GITHUB_WORKSPACE/weaver-ui/docker-compose.yml up -d registry @@ -34,19 +34,19 @@ jobs: uses: actions/cache@v3 with: path: ~/.npm - key: ${{ runner.os }}-node-${{ hashFiles('**/package.json', '**/package-lock.json') }} + key: ${{ runner.os }}-cache-node-${{ hashFiles('**/package.json', '**/package-lock.json') }} - name: "Node Modules Cache" uses: actions/cache@v3 with: - path: node_modules - key: ${{ runner.os }}-node_modules-${{ hashFiles('**/package.json', '**/package-lock.json') }} + path: $GITHUB_WORKSPACE/repo/node_modules + key: ${{ runner.os }}-cache-node_modules-${{ hashFiles('**/package.json', '**/package-lock.json') }} - name: "Maven Cache" uses: actions/cache@v3 with: path: ~/.m2/repository - key: ${{ runner.os }}-maven-${{ hashFiles('**/pom.xml') }} + key: ${{ runner.os }}-cache-maven-${{ hashFiles('**/pom.xml') }} - name: "Setup Node" uses: actions/setup-node@v3 @@ -58,7 +58,7 @@ jobs: with: java-version: 11 - - name: "Maven Tests" + - name: "Maven Test" env: NPM_CONFIG_REGISTRY: http://localhost:4873 run: | @@ -75,7 +75,7 @@ jobs: uses: MikeEdgar/github-action@raw_coverage_file with: github-token: ${{ secrets.github_token }} - path-to-file: repo/coveralls.json + path-to-file: 'repo/coveralls.json' coverage-format: raw # - name: "Lighthouse Report" @@ -86,7 +86,7 @@ jobs: # xvfb-run --auto-servernum npm run test:audit - name: "Deploy GH-Pages" - if: github.ref == 'refs/heads/master' && github.event_name == 'push' + if: github.ref == 'refs/heads/main' && github.event_name == 'push' uses: JamesIves/github-pages-deploy-action@3.7.1 with: github_token: ${{ secrets.github_token }} diff --git a/.gitignore b/.gitignore index 0169e193..b79a5972 100644 --- a/.gitignore +++ b/.gitignore @@ -1,33 +1,105 @@ -h2/ -bin/ -public/ -target/ -private/ -attachments/ -node_modules/ -*node_modules* -*.db +### Git ### +!.gitkeep -.vscode/ -.apt_generated/ -.tmp -.project -.settings +### STS ### +.apt_generated .classpath -.sass-cache .factorypath -.tern-project -.externalToolBuilders +.project +.settings +.springBeans +.sts4-cache -logs/ +### IntelliJ IDEA ### +.idea +*.iws +*.iml +*.ipr + + +### NetBeans ### +/nbproject/private/ +/nbbuild/ +/dist/ +/nbdist/ + +/.nb-gradle/ + +### VS Code ### +.vscode/ + +dump.rdb + + +### BlueJ ### +*.ctxt + + +### OS Specific ### .DS_Store +.tmp/ + +tmp/ + + +### Node / NPM ### +coverage/ +logs/ +node_modules/ + +.npmrc + +npm-debug.log package-lock.json -.env -.wvr/tmp/ +### Virtual Machine ### +hs_err_pid* +replay_pid* + + +### Java ### +.mtj.tmp/ + +*.class +*.log + +*.jar +*.war +*.nar +*.ear +*.zip +*.tar.gz +*.rar + + +### Maven ### +logs/ +target/ + +.classpth +.mvn/timing.properties +.mvn/wrapper/maven-wrapper.jar +.project + +buildNumber.properties +dependency-reduced-pom.xml +pom.xml.next +pom.xml.tag +pom.xml.releaseBackup +pom.xml.versionsBackup +release.properties + + +### Weaver ### dist/ -coverage/ + + +### Project Specific ### +.env* + +!**/src/main/** +!**/src/test/** diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92d0419e..a4d66d07 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,76 +1,65 @@ -# Contributing To SAGE + +# Contributing to Search Aggregation Engine -Though SAGE is developed and maintained by Texas A&M University Libraries, we welcome community contributions. Involvement in SAGE can take many forms: +Though *Search Aggregation Engine (SAGE)* is developed and maintained by Texas A&M University Libraries, we welcome community contributions. +Involvement in *SAGE* can take many forms. -#### Using SAGE: +
(back to top)
-Deploying SAGE and trying it out at your own institution is itself a way of contributing to the development process. For more information on deployment strategies please see the [relevant documentation](https://github.com/TAMULib/Sage/blob/master/README.md). - -#### Filing Issues: -Once you are using SAGE the creation of new issues through Github is a major method of contribution towards SAGE development. Issues can be motivated by the discovery of a bug in the software, or by the desire to see either new features added to cap or existing features behaving differently. +## Using -These three categories of issue can be submitted using the following template: +Deploying *SAGE* and trying it out at your own institution is itself a way of contributing to the development process. +For more information on deployment strategies please see the [Deployment Guide][deployment-guide]. -``` -[*] Bug Report -[] Feature Enhancement -[] Feature Request +
(back to top)
-Current Behavior: -[A description of the current behavior. This could include a list of steps to reproduce in the instance of a -Bug Report, and can be 'N/A' for Feature Requests] +## Filing Issues -Desired Behavior: +Once you are using *SAGE* the creation of new issues through GitHub is a major method of contribution towards *SAGE* development. +Issues can be motivated by the discovery of a bug in the software, or by the desire to see either new features added or see changes to existing features. -[A description of the expected/desired behavior of the application] +There are two primary types of issues: +1. Bug Report +2. Feature Request +A **Bug Report** involves a problem with the existing software or a **Feature** is not working as designed or expected. -Relevant Information: +A **Feature** involves new functionality or behavior. -[This section can include relevant error messages, or links to information that pertains to the issue] +
(back to top)
-```` -Once an issue has been filed it will be curated by a SAGE developer and receive the appropriate labeling. +## Creating a Pull Request -#### Creating Pull Requests: +Community code and documentation contributions are welcome and should take the form of a **GitHub Pull Request** (*PR*). +Each *PR* will need to be reviewed by a *SAGE* developer. +A review will result in the *PR* being accepted and merged, a descriptive request for changes, or the *PR* being closed along with a detailed explanation. -Community code and documentation contributions are welcome, and should take the form of a Github Pull Request (PR). Each PR will need to be reviewed by a SAGE developer. A review will result in the PR being accepted and merged, a descriptive request for changes, or the PR being closed along with a detailed explanation. +It is our intention to maintain labeling on issues that are deemed to be low difficulty in order to provide a good point of entry for those looking to begin contributing code or documentation. -It is our intention to maintain labeling on issues that are deemed to be low difficulty, in order to provide a good point of entry for those looking to begin contributing code or documentation. +A *PR* description should include a list of the specific issues resolved, the predicted *semantic versioning* impact of the changes, and a description which characterizes the nature of the changes made. +When creating a *PR*, an issue template is automatically provided to simplify this process. -A PR description should include a list of the specific issues resolved, the predicted semantic versioning impact of the changes and a description which characterizes the nature of the changes made. +For more information about *semantic versioning* please see [Semantic Versioning Website][semantic-versioning]. +In general keep in mind: -For more information about semantic versioning please see [this reference](https://semver.org/). In general keep in mind: +- A **Major Change** is a breaking change that is not backwards compatible. +- A **Minor Change** is a non-breaking change that is backwards compatible to the last **Major Change**. +- A **Patch** is a trivial change or bug fix that should not impact compatibility. -- A Major Change is a breaking change that is not backwards compatible. -- A Minor Change is a non breaking change that is backwards compatible to the last major change. -- A Patch is a trivial change or bug fix that should not impact compatibility +
(back to top)
-Please confirm you PR description to the following template: -``` -Resolves: +## Good Luck! -- [List of # references to specific issues addressed by this PR] +We look forward to seeing your contributions. +If you have any additional questions please contact the *SAGE* developers at helpdesk@library.tamu.edu. -Changes: +
(back to top)
-[*] Major -[] Minor -[] Patch -[A description of the approach taken to resolving those issues] - -``` - -In addition to a well formatted PR we would also appreciate granular commits with descriptive messages. For instance a good commit message may be `Moved /foo endpoint logic into a FooService`, whereas `Everything I did Friday` is less granular or descriptive. - -If your commits do not conform to these recommendations you might consider rebasing your PR. Instructions for how this might work can be found [here](https://help.github.com/articles/about-git-rebase/). - - -#### Good Luck! - -We look forward to seeing your contributions. If you have any additional questions please contact the SAGE developers at [helpdesk@library.tamu.edu](). + +[deployment-guide]: DEPLOYING.md +[semantic-versioning]: https://semver.org/ diff --git a/DEPLOYING.md b/DEPLOYING.md index 9b891b5f..609d46b7 100644 --- a/DEPLOYING.md +++ b/DEPLOYING.md @@ -1,74 +1,216 @@ -The DEPLOYING documentation is currently a work in progress. - -### Development with Weaver - -* Clone [Weaver-UI-Core](git@github.com:TAMULib/Weaver-UI-Core.git) -* Start docker compose within Weaver-UI-Core directory. - -```sh -docker-compose up -``` - -* Copy the `example.env` file and call it `.env`. These are build args and container environment variables used in docker-compose.yml. -* Change variables as needed. -* Run `docker-compose` commands. - -```sh -docker-compose build --no-cache -docker-compose up -``` - -### AUTHORIZATION - -By default, SAGE is configured to support email based registration and authorization with password ('emailRegistration'). There is generally no need to change this. - -SAGE can also be configured to use Weaver Authentication ('weaverAuth'), an external authorization abstraction which brings additional identity provider support into the Weaver platform. - -### ADVANCED AUTHORIZATION CONFIGURATION - -The SAGE UI's appConfig object has an 'authStrategies' property that accepts a list of strings representing the active auth strategies: - -https://github.com/TAMULib/SAGE/blob/master/build/appConfig.js.template#L8 - -The SAGE UI displays different login prompts and exhibits certain behaviors based on the authStrategies property: - -https://github.com/TAMULib/SAGE/blob/master/src/main/webapp/app/controllers/appLoginController.js - -https://github.com/TAMULib/SAGE/blob/master/src/main/webapp/app/views/modals/loginModal.html - -When emailRegistration is active, the 'appLoginController', an extension of Weaver's LoginController is used. When 'weaverAuth' is active, a controller provided by Weaver UI Core is used. - -If you are using an auth service other than SAGE's built in service, you will need to provide its url using the 'authService' property, also part of the appConfig object: - -https://github.com/TAMULib/SAGE/blob/master/build/appConfig.js.template#L10 - -It's most common to choose one authentication strategy, but it is technically possible to support two or more strategies simultaneously by listing each entry separated by commas. - - -### DEVELOPMENT ONLY - -The SAGE service can also be run with a development only profile that provides mock auth credentials. - -This is activated by choosing 'mock-token-provider' as the active profile in application.yml: - -https://github.com/TAMULib/SAGE/blob/master/src/main/resources/application.yml - -And pointing the SAGE UI to the mock auth API by setting the appConfig object's 'authService' property to: - -window.location.protocol + '//' + window.location.host + window.location.base + '/mock/auth' - -https://github.com/TAMULib/SAGE/blob/master/build/appConfig.js.template - -The authorization level of the mock user is determined by the 'mockRole' property, also on the appConfig object: - -https://github.com/TAMULib/SAGE/blob/master/build/appConfig.js.template - - -### CUSTOMIZING AUTH STRATEGIES - -The emailRegistration strategy can be customized by altering the AuthController java class: -https://github.com/TAMULib/SAGE/blob/master/src/main/java/edu/tamu/sage/auth/controller/AuthController.java - -It is also possible to substitute this class for a different class by having that class extend edu.tamu.weaver.auth.controller.WeaverAuthController. - -You will also need to remove the @RestController and @RequestMapping("/auth") annotations from AuthController and add them to your new class. Under the hood, the Weaver Framework uses the "/auth" api endpoint to pass auth tokens to client applications. \ No newline at end of file + +# Search Aggregation Engine Deployment Guide + + +## Configuration + +There are several files that allow for configuration: + +* The `.env` file. +* The `src/main/resources/application.yml` file. +* The `build/appConfig.js.template` file. + +Most settings can and should be configured using the `.env` file when using `docker-compose`. +In other cases, either passing environment variables to `docker`, manually exporting environment variables, or directly editing the configuration files may be necessary. + +The `src/main/resources/application.yml` file can be configured through environment variables. +Consult the [Spring Documentation][spring-docs-binding] in regards to this. + +The `build/appConfig.js.template` has limited support for environment variables but for those that are exposed may be altered using the `.env` file. + + +### Authorization + +By default, *SAGE* is configured to support e-mail based registration and authorization using passwords using the `emailRegistration` setting. +There is generally no need to change this. + +*SAGE* can also be configured to use *Weaver Authentication* using the `weaverAuth` setting. +The *Weaver Authentication* is an external authorization abstraction which brings additional identity provider support into the platform. + + +### Advanced Authorization + +The *SAGE UI*'s appConfig object has an `authStrategies` property that accepts a list of strings representing the active auth strategies: + +``` + 'authStrategies': ['emailRegistration'], +``` + +The *SAGE UI* displays different login prompts and exhibits certain behaviors based on the `authStrategies` property. + +When `emailRegistration` is active, the `appLoginController`, an extension of **Weaver's** `LoginController` is used. +When `weaverAuth` is active, a controller provided by **Weaver UI Core** is used. + +If you are using an auth service other than *SAGE's* built in service, you will need to provide its url using the 'authService' property, also part of the appConfig object: + +It's most common to choose a single authentication strategy, but it is technically possible to support multiple strategies simultaneously by listing each entry separated by commas. + + +### Mocked Authorization + +The *SAGE* service can also be run with a development only profile that provides mock auth credentials. + +This is activated by choosing `mock-token-provider` as the active profile in `application.yml` (or via an appropriate environment variable): + +``` +spring.profiles.active: mock-token-provider +``` + + +### Customizing Authorization Strategies + +The `emailRegistration` strategy can be customized by altering the `AuthController.java` class. + +It is also possible to substitute this class for a different class by having that class extend `edu.tamu.weaver.auth.controller.WeaverAuthController`. + +You will also need to remove the `@RestController` and `@RequestMapping("/auth")` annotations from `AuthController` and add them to your new class. +Under the hood, the **Weaver Framework** uses the `"/auth"` API endpoint to pass auth tokens to client applications. + +
(back to top)
+ + +## Production Deployments + +For **production** deployments, deploy using `docker-compose`. +This is the recommended method of deployment for production systems. + +Perform the following steps to deploy (with an existing [Solr][solr-url] index): + +```shell +git clone https://github.com/TAMULib/SAGE.git SAGE + +cd SAGE/ + +cp example.env .env + +# Make any changes to the .env file before here (see the configuration sections). +docker-compose up +``` + +If an existing [Solr][solr-url] index is not available, then perform the following after copying the `.env` file. + +```shell +cd SAGE/solr +docker build -t sage/solr . +docker run -p 8983:8983 -it sage/solr +``` + +_* Note: when using the same terminal to start both the [Solr][solr-url] index and *SAGE*, the `-d` parameter may be useful to detach when running (`docker run -p 8983:8983 -dit sage/solr`)._ + +The **development** deployment can also use `docker-compose` in the same way. + +
(back to top)
+ + +## Development Deployment using Docker + +To manually use `docker` rather than `docker-compose`, run the following: + +```shell +docker image build -t project . +docker run -it project +``` + +_* Note: `-t project` and `-it project` may be changed to another tag name as desired, such as `-t developing_on_this` and `-it developing_on_this`._
+_** Note: An additional step may be required, such as deploying alongside a [Weaver UI Core][weaver-ui] instance using [Verdaccio][verdaccio]._ + +To deploy alongside a [Weaver UI Core][weaver-ui] instance using [Verdaccio][verdaccio], do the following *before* deploying: + +```shell +cd Weaver-UI-Core +docker image build -t weaver-ui . +docker run -it weaver-ui +``` + +The host system affects the network being used and is different from **Windows** to **Mac** to **Linux**. +* The `--network=` argument may be needed to assist with this, such as `--network=weaver`. +* The `--build-arg` may be needed to use the appropriate **NPM** registry settings, such as `--build-arg=NPM_REGISTRY="docker-linux"`. +* More network related changes may be required, so please consult the appropriate **Docker** documentation. + +
(back to top)
+ + +## Development Deployment using NPM and Maven + +Manual deployment can be summed up by running: + +**NPM** + +```shell +npm install +npm run build +npm run start +``` + +**Maven** + +```shell +mvn clean spring-boot:run +``` + +Those steps are a great way to start but they also fail to explain the customization that is often needed. +There are multiple ways to further configure this for deployment to better meet the desired requirements. + +It is highly recommended only to perform *manual installation* when developing. +For production deployment, please use either the `docker-compose` method or the **Docker** method above. + +
(back to top)
+ + +### Directly Configuring the `dist/appConfig.js` File + +This method of configuration works by altering the built distribution configuration file. +This file is deleted every time either `npm run build` or `npm run clean` are run. +But in the event that a quick and manual change is needed, this is the simplest way to do so. + +With this in mind, the deployment steps now look like: + +```shell +npm install +npm run build +dist/appConfig.js +npm run start +``` + +_* Remember, changes to `dist/appConfig.js` are lost every time `npm run build` is run._ + +
(back to top)
+ + +### Directly Configuring the `.wvr/build-config.js` Build File + +This method of configuration is only recommended for `advanced uses` but is otherwise not recommended. +The advantage of this method of configuration is that of preserving the changes between _build_ or _clean_ commands. +There is only a small section that should be changed. + +The `.wvr/build-config.js` file has only a single section of interest and might look something like this: + +```js + { + from: './build/appConfig.js.template', + to: './appConfig.js', + transform(content) { + return content + .toString() + .replace('${AUTH_STRATEGY}', 'weaverAuth') + .replace('${AUTH_SERVICE_URL}', 'https://labs.library.tamu.edu/authfix') + .replace('${STOMP_DEBUG}', 'false') + .replace('${AVALON_URL}', 'avalon-pre.library.tamu.edu:443'); + }, + }, +``` + +In the above example snippet, only the lines containing `'${AUTH_STRATEGY}'`, `'${AUTH_SERVICE_URL}'`, `'${STOMP_DEBUG}'`, and `'${AVALON_URL}'` should be changed. +For example `'https://labs.library.tamu.edu/authfix'` could be changed to `'https://labs.library.tamu.edu:8443/authfix'` (changing the port number from 443 to 8443). + +Once this is done all of the steps from *Development Deployment using NPM and Maven* above can be followed. + +
(back to top)
+ + + +[weaver-ui]: https://github.com/TAMULib/Weaver-UI-Core +[verdaccio]: https://verdaccio.org +[solr-url]: https://solr.apache.org/ + +[spring-docs-binding]: https://docs.spring.io/spring-boot/docs/2.0.x/reference/html/boot-features-external-config.html#boot-features-external-config-relaxed-binding diff --git a/Dockerfile b/Dockerfile index 56a87e79..75a809c9 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,62 +1,58 @@ # Settings. -ARG PROFILE=production ARG USER_ID=3001 ARG USER_NAME=sage -ARG HOME_DIR=/$USER_NAME -ARG SOURCE_DIR=$HOME_DIR/source -ARG NPM_REGISTRY_URL=upstream +ARG SOURCE_DIR=/$USER_NAME/source +ARG NPM_REGISTRY=upstream ARG NODE_ENV=development # Maven stage. FROM maven:3-openjdk-11-slim as maven -ARG PROFILE ARG USER_ID ARG USER_NAME -ARG HOME_DIR ARG SOURCE_DIR -ARG NPM_REGISTRY_URL +ARG NPM_REGISTRY ARG NODE_ENV ENV NODE_ENV=$NODE_ENV -# Create the group (use a high ID to attempt to avoid conflits). -RUN groupadd --non-unique -g $USER_ID $USER_NAME - -# Create the user (use a high ID to attempt to avoid conflits). -RUN useradd --non-unique -d $HOME_DIR -m -u $USER_ID -g $USER_ID $USER_NAME +# Create the user and group (use a high ID to attempt to avoid conflicts). +RUN groupadd --non-unique -g $USER_ID $USER_NAME && \ + useradd --non-unique -d /$USER_NAME -m -u $USER_ID -g $USER_ID $USER_NAME # Install stable Nodejs and npm. -RUN \ - apt-get update \ - && apt-get -y install nodejs npm iproute2 \ - && apt-get clean \ - && rm -rf /var/lib/apt/lists/* \ - && npm cache clean -f \ - && npm install -g n \ - && n stable +RUN apt-get update && \ + apt-get upgrade -y && \ + apt-get install -y nodejs npm iproute2 && \ + apt-get clean && \ + rm -rf /var/lib/apt/lists/* && \ + npm cache clean -f && \ + npm install -g n && \ + n stable + +# Ensure source directory exists and has appropriate file permissions. +RUN mkdir -p $SOURCE_DIR && \ + chown $USER_ID:$USER_ID $SOURCE_DIR && \ + chmod g+s $SOURCE_DIR # Set deployment directory. WORKDIR $SOURCE_DIR -# Copy files over. +# Copy in files from outside of docker. COPY ./pom.xml ./pom.xml COPY ./.wvr/build-config.js ./.wvr/build-config.js COPY ./src ./src COPY ./build ./build COPY ./package.json ./package.json -# Copy NPM registry helper script. -COPY build/docker-npmrc.sh ${SOURCE_DIR}/docker-npmrc.sh - # Assign file permissions. -RUN chown -R ${USER_ID}:${USER_ID} ${SOURCE_DIR} +RUN chown -R $USER_ID:$USER_ID $SOURCE_DIR # Login as user. USER $USER_NAME # Perform actions. -RUN echo $NPM_REGISTRY_URL -RUN bash ${SOURCE_DIR}/docker-npmrc.sh $NPM_REGISTRY_URL +RUN echo $NPM_REGISTRY && \ + bash $SOURCE_DIR/build/docker-npmrc.sh $NPM_REGISTRY # Build. RUN mvn package -Pjar -DskipTests @@ -65,52 +61,48 @@ RUN mvn package -Pjar -DskipTests FROM openjdk:11-jre-slim ARG USER_ID ARG USER_NAME -ARG HOME_DIR ARG SOURCE_DIR -RUN \ - apt-get update \ - && apt-get -y install gettext-base \ - && apt-get clean \ - && rm -rf /var/lib/apt/lists/* +RUN apt-get update && \ + apt-get upgrade -y && \ + apt-get -y install gettext-base && \ + apt-get clean && \ + rm -rf /var/lib/apt/lists/* # Copy files from outside docker to inside. COPY build/appConfig.js.template /usr/local/app/templates/appConfig.js.template COPY build/docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh # Enable execute of docker entrypoint for root user. -RUN \ - chmod ugo+r /usr/local/app/templates/appConfig.js.template \ - && chmod ugo+rx /usr/local/bin/docker-entrypoint.sh - -# Create the group (use a high ID to attempt to avoid conflits). -RUN groupadd --non-unique -g $USER_ID $USER_NAME +RUN chmod ugo+r /usr/local/app/templates/appConfig.js.template && \ + chmod ugo+rx /usr/local/bin/docker-entrypoint.sh -# Create the user (use a high ID to attempt to avoid conflits). -RUN useradd --non-unique -d $HOME_DIR -m -u $USER_ID -g $USER_ID $USER_NAME +# Create the user and group (use a high ID to attempt to avoid conflicts). +RUN groupadd --non-unique -g $USER_ID $USER_NAME && \ + useradd --non-unique -d /$USER_NAME -m -u $USER_ID -g $USER_ID $USER_NAME # Login as user. USER $USER_NAME # Set deployment directory. -WORKDIR $HOME_DIR +WORKDIR /$USER_NAME # Copy over the built artifact and library from the maven image. COPY --from=maven $SOURCE_DIR/target/ROOT.jar ./sage.jar COPY --from=maven $SOURCE_DIR/target/libs ./libs -ENV AUTH_STRATEGY weaverAuth +ENV AUTH_STRATEGY=weaverAuth -ENV STOMP_DEBUG false +ENV STOMP_DEBUG=false -ENV AUTH_SERVICE_URL http://localhost:9001/auth -ENV AVALON_URL avalon-pre.library.tamu.edu:443 +ENV AUTH_SERVICE_URL=http://localhost:9001/auth +ENV AVALON_URL=avalon-pre.library.tamu.edu:443 -ENV APP_CONFIG_PATH=file:$HOME_DIR/appConfig.js +ENV APP_CONFIG_PATH=file:/$USER_NAME/appConfig.js EXPOSE 9000 -# Entrypoint to perform environment substitution on appConfig.js. +# Entrypoint performs environment substitution on appConfig.js. ENTRYPOINT ["docker-entrypoint.sh"] # Run java command. diff --git a/LICENSE b/LICENSE index 5cf83463..9d020117 100644 --- a/LICENSE +++ b/LICENSE @@ -1,21 +1,8 @@ -MIT License +The MIT License (MIT) +Copyright © 2022 Texas A&M University Libraries -Copyright (c) 2022 Texas A&M University Libraries +Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. +THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index 07a3cf68..6b158ac9 100644 --- a/README.md +++ b/README.md @@ -1,38 +1,80 @@ -[![Build Status](https://github.com/TAMULib/SAGE/workflows/Build/badge.svg)](https://github.com/TAMULib/SAGE/actions?query=workflow%3ABuild) -[![Coverage Status](https://coveralls.io/repos/github/TAMULib/SAGE/badge.svg)](https://coveralls.io/github/TAMULib/SAGE) + +[![Build Status][build-badge]][build-status] +[![Coverage Status][coverage-badge]][coverage-status] -# SAGE -SAGE is the Search Aggregation Engine developed and maintained by [Texas A&M University Libraries](http://library.tamu.edu). +# Search Aggregation Engine -SAGE’s feature set includes both the ability aggregate disparate searchable sources into a common Solr index, as well as the ability expose Solr indexes through a dynamic user interface. +*Search Aggregation Engine (SAGE)*, consisting of a service back-end and a client front-end, is developed and maintained by [Texas A&M University Libraries][tamu-library]. -### User Documentation +*SAGE's* feature set includes both the ability aggregate disparate searchable sources into a common [Solr][solr-url] index, as well as the ability expose [Solr][solr-url] indexes through a dynamic user interface. -SAGE boasts an intuitive user interface, but some much needed user documentation is currently a work in progress. +
(back to top)
-### SAGE Default Solr -```bash - cd SAGE/solr - docker build --tag=sage/solr . - docker run -p 8983:8983 sage/solr -``` +## User Documentation + +*CAP* user documentation can be found in [the wiki][user-docs]. + +For more technical users, deployment related configurations are described in the [Deployment Guide][deployment-guide]. + +
(back to top)
+ -### Deployment +## Deployment + +A quick and easy deployment method using `docker-compose` is described in the [Deployment Guide][deployment-guide]. + +For _advanced use cases_, or when `docker-compose` is unavailable, the use of `docker` or `npm`/`mvn` is also described in the [Deployment Guide][deployment-guide]. + +Deployment, in general, may look something like this: + +```shell +cd solr +docker build -t sage/solr . +docker run -p 8983:8983 -it sage/solr +``` -* Copy the `example.env` file and call it `.env`. These are build args used in docker-compose.yml. -* Change variables as needed. -* Run `docker-compose` commands. +```shell +cp example.env .env +cp example.env.client .env.client +cp example.env.service .env.service -```sh +# Make any changes to the .env, .env.client, and .env.service files before here. docker-compose up ``` -### Developer Documentation +_* Note: It may be necessary to disable caching during build by passing `--no-cache` to the `docker-compose up` command._ + +
(back to top)
+ + +## Additional Resources + +- [Contributors Documentation][contribute-guide] +- [Deployment Documentation][deployment-guide] +- [API Documentation][api-docs] + +Please feel free to file any issues concerning *SAGE* to the issues section of the repository. + +Any questions concerning *SAGE* can be directed to helpdesk@library.tamu.edu. + +Copyright © 2022 Texas A&M University Libraries under the [MIT License][license]. + +
(back to top)
+ + + +[build-status]: https://github.com/TAMULib/SAGE/actions?query=workflow%3ABuild +[build-badge]: https://github.com/TAMULib/SAGE/workflows/Build/badge.svg +[coverage-status]: https://coveralls.io/github/TAMULib/SAGE +[coverage-badge]: https://coveralls.io/repos/github/TAMULib/SAGE/badge.svg -- [Contributors Documentation](https://github.com/TAMULib/SAGE/blob/master/CONTRIBUTING.md) -- [Deployment Documentation](https://github.com/TAMULib/SAGE/blob/master/DEPLOYING.md) -- [API Documentation](https://tamulib.github.io/SAGE) +[tamu-library]: http://library.tamu.edu +[api-docs]: https://tamulib.github.io/SAGE +[user-docs]: https://github.com/TAMULib/SAGE/wiki +[solr-url]: https://solr.apache.org/ -Please feel free to file any issues concerning SAGE to the issues section of the repository. Any questions concerning SAGE can be directed to [helpdesk@library.tamu.edu]() +[deployment-guide]: DEPLOYING.md +[contribute-guide]: CONTRIBUTING.md +[license]: LICENSE diff --git a/build/appConfig.js.template b/build/appConfig.js.template index 3cf3886e..e7aabd6c 100644 --- a/build/appConfig.js.template +++ b/build/appConfig.js.template @@ -1,7 +1,5 @@ var appConfig = { - 'version': '1.3.3', - 'allowAnonymous': true, 'anonymousRole': 'ROLE_ANONYMOUS', diff --git a/docker-compose.yml b/docker-compose.yml index 68bba96e..01a7a620 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -13,9 +13,9 @@ services: dockerfile: Dockerfile context: './' args: - - NPM_REGISTRY_URL=${NPM_REGISTRY_URL} + - NPM_REGISTRY=${NPM_REGISTRY} - NODE_ENV=${NODE_ENV} - image: ${IMAGE_HOST}/${SERVICE_PROJECT}/sage:${IMAGE_VERSION} + image: ${IMAGE_HOST}/${SERVICE_PROJECT}${SERVICE_PATH}:${IMAGE_VERSION} ports: - 9000:9000 env_file: diff --git a/example.env b/example.env index acca1f2d..a504f3b0 100644 --- a/example.env +++ b/example.env @@ -4,15 +4,20 @@ ############################## IMAGE_HOST=127.0.0.1 + IMAGE_VERSION=0.0.1 + SERVICE_PROJECT=tomcatapps +# Must have leading slash. +SERVICE_PATH=/sage + # Which npm registry URL to use. # upstream https://registry.npmjs.org/ # docker-linux http://$(ip route | awk '/default/ { print $3 }'):4873 # docker-mac http://host.docker.internal:4873 # docker-windows http://host.docker.internal:4873 -NPM_REGISTRY_URL=upstream +NPM_REGISTRY=upstream NODE_ENV=production diff --git a/karma.conf.js b/karma.conf.js index fcbdb45f..8ce932c4 100644 --- a/karma.conf.js +++ b/karma.conf.js @@ -3,119 +3,97 @@ module.exports = function (config) { preprocessors: { 'src/main/webapp/app/**/*.js': 'coverage', - 'src/main/webapp/app/views/**/*.html': ['ng-html2js'] + 'src/main/webapp/app/**/*.html': ['ng-html2js'], }, - reporters: ['progress', 'coverage'], + reporters: ['progress', 'coverage', 'coveralls'], basePath: './', files: [ 'dist/appConfig.js', - - "src/main/webapp/app/config/apiMapping.js", - - "node_modules/jquery/dist/jquery.js", - "node_modules/bootstrap/dist/js/bootstrap.js", - - "node_modules/sockjs-client/dist/sockjs.js", - "node_modules/stompjs/lib/stomp.js", - - "node_modules/angular/angular.js", - - "node_modules/angular-sanitize/angular-sanitize.js", - "node_modules/angular-route/angular-route.js", - "node_modules/angular-loader/angular-loader.js", - "node_modules/angular-messages/angular-messages.js", - "node_modules/angular-mocks/angular-mocks.js", - - "node_modules/angular-ui-bootstrap/dist/ui-bootstrap-tpls.js", - - "node_modules/ng-csv/build/ng-csv.js", - - "node_modules/ng-table/bundles/ng-table.js", - - "node_modules/ng-file-upload/dist/ng-file-upload-shim.js", - "node_modules/ng-file-upload/dist/ng-file-upload.js", - + 'src/main/webapp/app/config/apiMapping.js', + + 'node_modules/jquery/dist/jquery.js', + 'node_modules/bootstrap/dist/js/bootstrap.js', + 'node_modules/sockjs-client/dist/sockjs.js', + 'node_modules/stompjs/lib/stomp.js', + 'node_modules/angular/angular.js', + 'node_modules/angular-sanitize/angular-sanitize.js', + 'node_modules/angular-route/angular-route.js', + 'node_modules/angular-loader/angular-loader.js', + 'node_modules/angular-messages/angular-messages.js', + 'node_modules/angular-mocks/angular-mocks.js', + 'node_modules/angular-ui-bootstrap/dist/ui-bootstrap-tpls.js', + 'node_modules/ng-csv/build/ng-csv.js', + 'node_modules/ng-table/bundles/ng-table.js', + 'node_modules/ng-file-upload/dist/ng-file-upload-shim.js', + 'node_modules/ng-file-upload/dist/ng-file-upload.js', 'node_modules/openseadragon/build/openseadragon/openseadragon.js', 'node_modules/ng-openseadragon/build/angular-openseadragon.js', - - "node_modules/jasmine-promise-matchers/dist/jasmine-promise-matchers.js", - - "node_modules/@wvr/core/app/config/coreConfig.js", - - "node_modules/@wvr/core/app/components/**/*.js", - - "node_modules/@wvr/core/app/core.js", - - "node_modules/@wvr/core/app/**/*.js", - - "src/main/webapp/tests/testSetup.js", - - "src/main/webapp/app/app.js", - - "src/main/webapp/app/components/**/*.js", - - "src/main/webapp/app/config/runTime.js", - - "src/main/webapp/app/controllers/**/*.js", - - "src/main/webapp/app/directives/**/*.js", - - "src/main/webapp/app/filters/**/*.js", - - "src/main/webapp/app/model/**/*.js", - - "src/main/webapp/app/repo/**/*.js", - - "src/main/webapp/app/services/**/*.js", - - "src/main/webapp/app/views/**/*.html", - - "src/main/webapp/tests/core/**/*.js", - - "src/main/webapp/tests/mock/**/*.js", - - "src/main/webapp/tests/unit/**/*.js" + 'node_modules/jasmine-promise-matchers/dist/jasmine-promise-matchers.js', + + 'node_modules/@wvr/core/app/config/coreConfig.js', + 'node_modules/@wvr/core/app/components/**/*.js', + 'node_modules/@wvr/core/app/core.js', + 'node_modules/@wvr/core/app/**/*.js', + + 'src/main/webapp/tests/testSetup.js', + + 'src/main/webapp/app/app.js', + 'src/main/webapp/app/config/runTime.js', + 'src/main/webapp/app/components/**/*.js', + 'src/main/webapp/app/constants/**/*.js', + 'src/main/webapp/app/controllers/**/*.js', + 'src/main/webapp/app/directives/**/*.js', + 'src/main/webapp/app/filters/**/*.js', + 'src/main/webapp/app/model/**/*.js', + 'src/main/webapp/app/repo/**/*.js', + 'src/main/webapp/app/services/**/*.js', + 'src/main/webapp/app/**/*.html', + + 'src/main/webapp/tests/core/**/*.js', + 'src/main/webapp/tests/mock/**/mock*.js', + 'src/main/webapp/tests/unit/**/*Test.js', ], autoWatch: true, - frameworks: ["jasmine"], + frameworks: ['jasmine'], - browsers: ["Firefox", "Chrome", "ChromeHeadless", "ChromeHeadlessNoSandbox"], + browsers: ['ChromeHeadless'], customLaunchers: { ChromeHeadlessNoSandbox: { - base: "ChromeHeadless", - flags: ["--no-sandbox"] + base: 'ChromeHeadless', + flags: ['--no-sandbox'], } }, plugins: [ - "karma-chrome-launcher", - "karma-coverage", - "karma-firefox-launcher", - "karma-jasmine", - "karma-junit-reporter", - "karma-ng-html2js-preprocessor" + 'karma-chrome-launcher', + 'karma-coverage', + 'karma-coveralls', + 'karma-firefox-launcher', + 'karma-jasmine', + 'karma-junit-reporter', + 'karma-ng-html2js-preprocessor', ], junitReporter: { - outputFile: "test_out/unit.xml", - suite: "unit" + outputFile: 'test_out/unit.xml', + suite: 'unit', }, ngHtml2JsPreprocessor: { - stripPrefix: "src/main/webapp/app/", - moduleName: "templates" + stripPrefix: 'src/main/webapp/app/', + moduleName: 'templates', }, coverageReporter: { - type: "lcov", - dir: "coverage/", - subdir: '.' + type: 'lcov', + dir: 'coverage/', + subdir: '.', } }); diff --git a/pom.xml b/pom.xml index 4473df0b..d69b80f7 100644 --- a/pom.xml +++ b/pom.xml @@ -12,7 +12,7 @@ edu.tamu.weaver webservice-parent - 2.1.1-RC10 + 2.1.1-RC11 diff --git a/src/test/resources/logback-test.xml b/src/test/resources/logback-test.xml index 1c91122e..5c6cfb6a 100644 --- a/src/test/resources/logback-test.xml +++ b/src/test/resources/logback-test.xml @@ -1,7 +1,6 @@ - - +