diff --git a/Gemfile.lock b/Gemfile.lock index a6c047b4..d63b1d77 100644 --- a/Gemfile.lock +++ b/Gemfile.lock @@ -384,7 +384,7 @@ GEM mini_histogram (0.3.1) mini_mime (1.1.5) minitar (0.9) - minitest (5.20.0) + minitest (5.21.1) mock_redis (0.39.0) msgpack (1.7.2) multi_json (1.15.0) @@ -447,7 +447,7 @@ GEM psych (5.1.1.1) stringio public_suffix (4.0.7) - puma (6.4.0) + puma (6.4.2) nio4r (~> 2.0) raabro (1.4.0) racc (1.7.3) @@ -641,7 +641,7 @@ GEM unf_ext (0.0.9.1) unicode-display_width (2.5.0) version_gem (1.1.3) - view_component (3.8.0) + view_component (3.10.0) activesupport (>= 5.2.0, < 8.0) concurrent-ruby (~> 1.0) method_source (~> 1.0) diff --git a/README.md b/README.md index 7db80e4c..344c8551 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,222 @@ -# README +# nla-blacklight -This README would normally document whatever steps are necessary to get the -application up and running. +[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/nla/nla-blacklight/verify.yml?branch=main&logo=github)](https://github.com/nla/nla-blacklight/actions/workflows/verify.yml) +[![GitHub release (latest SemVer including pre-releases)](https://img.shields.io/github/v/release/nla/nla-blacklight?include_prereleases)](https://github.com/nla/nla-blacklight/releases/latest) +[![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org) -Things you may want to cover: +Custom implementation of [Blacklight](http://projectblacklight.org/) for The National Library of Australia. -* Ruby version +## Table of Contents + +* [Requirements](#requirements) +* [Configuration](#configuration) + + [Environment Variables](#environment-variables) + - [Blacklight database](#blacklight-database) + - [Solr](#solr) + - [Temp and caching directories](#temp-and-caching-directories) + - [External services](#external-services) + - [Rails settings](#rails-settings) +* [Setup](#setup) +* [Running the app](#running-the-app) +* [Tests](#tests) +* [Continuous Integration](#continuous-integration) + + [Releases](#releases) +* [Deployment](#deployment) +* [Linting, Static Analysis & Supply Chain Vulnerability Checking](#linting--static-analysis---supply-chain-vulnerability-checking) + +## Requirements + +* Ruby: 3.2.2 +* Bundler: 2.4.22 * System dependencies + - Solr: 8 + - MySQL: 8 + - Redis: 7 + +* Gems: + - [blacklight-common](https://github.com/nla/nla-blacklight_common) + - [blacklight-solrcloud-repository](https://github.com/nla/blacklight-solrcloud-repository) + - [bento_search](https://github.com/nla/bento_search) + +## Contributing + +The [GoRails guide](https://gorails.com/setup) has great instructions for setting up Ruby, Rails and MySQL for your operating system. + +✏️ This repository uses [conventional commits](https://www.conventionalcommits.org) +and commit messages are used to generate `CHANGELOG.md` and release body entries. + +The most important prefixes you should have in mind are: + +* `fix:` which represents bug fixes, and correlates to a SemVer patch. +* `feat:` which represents a new feature, and correlates to a SemVer minor. +* `feat!:`, or `fix!:`, `refactor!:`, etc., which represent a breaking change (indicated by the !) and will result in a SemVer major. + +Releases are automated via GitHub workflows. See more in the ["Releases"](#releases) section. + +## Configuration + +All configurable values should be defined via environment variables. `dotenv` will automatically load values +from the `.env*` config in development and test environments. + +Non-sensitive values for development and test environments should be defined in the `.env.development`/`.env.test` files. + +Sensitive values can be defined in `.env.development.local` or `.env.test.local` files for local development +and *SHOULD NOT* be committed to source control. Git is configured to ignore these files. + +⚠️ If `dotenv` fails to load the configuration values into the environment, you can manually export these +values in your terminal before running the application. + +
+List of Environment Variables + +#### Blacklight database + DATABASE_URL - Application database for Blacklight + PATRON_DB_URL - Shared user and sessions database + REDIS_URL - Redis cache + +#### Solr + SOLR_URL - single node Solr + + ZK_HOST - Zookeeper connection string for the Solr Cloud cluster + SOLR_COLLECTION - Solr Cloud collection for the catalogue index + +#### Rails settings +These variables are mainly used in the `staging` or `production` environment. + + SECRET_KEY_BASE - used by Devise for encrypting session values + RAILS_LOG_TO_STDOUT - makes Rails logs print to the console + RAILS_SERVE_STATIC_FILES - tells Rails to serve static assets from the /public directory + +#### Temp and caching directories +These variables are mainly used in the `staging` or `production` environment. + + PIDFILE - relocates the server pid file outside of the application directory + BLACKLIGHT_TMP_PATH - relocates the caching directory outside of the application directory + +#### External services + GETALIBRARYCARD_BASE_URL - base URL for Get a Library Card + GETALIBRARYCARD_AUTH_PATH - path to the authentication endpoint of Get a Library Card + GETALIBRARYCARD_PATRON_DETAILS_PATH - path to the user details endpoint of Get a Library Card + + PATRON_AUTH_URL - base URL for User Registration (a.k.a. "UserReg") + PATRON_AUTH_ENDPOINT - path to the authentication endpoint + + KEYCLOAK_URL - URL of the Keycloak server + + KC_SOL_CLIENT - Staff Official Loan realm client name + KC_SOL_SECRET - Staff Official Loan realm client secret + KC_SOL_REALM - realm name for Staff Official Loan + + KC_SPL_CLIENT - Staff Personal Loan realm client name + KC_SPL_SECRET - Staff Personal Loan realm client secret + KC_SPL_REALM - realm name for Staff Personal Loan + + KC_SHARED_CLIENT - Team Official Loan account realm client name + KC_SHARED_SECRET - Team Official Loan account realm client secret + KC_SHARED_REALM - realm name for Team Official Loan account realm + + COPYRIGHT_SERVICE_URL - URL of the Copyright service + COPYRIGHT_FAIR_DEALING_URL - URL to the page describing copyright fair dealing + COPYRIGHT_CONTACT_URL - URL to the page describing how to contact the Library about copyright + + COPIES_DIRECT_URL - URL to Copies Direct + + ERESOURCES_CONFIG_URL - URL to the eResources configuration JSON endpoint + EZPROXY_URL - URL to the EZProxy server + EZPROXY_USER - username for EZProxy + EZPROXY_PASSWORD - password for EZProxy + + EDS_DEBUG - set to `y`/`n` to enable/disable debug logging for EDS API requests + EDS_PROFILE - EDS profile name + EDS_GUEST - set to `y`/`n` to enable/disable guest access for EDS API requests + EDS_USER - username for EDS API requests + EDS_PASSWORD - password for EDS API requests + EDS_AUTH - authentication method for EDS API requests + EDS_ORG - organisation ID for EDS API requests + EDS_CACHE_DIR - directory for EDS API request caching + + EBSCO_SEARCH_URL - URL to the EBSCO EDS API + CATALOGUE_SEARCH_URL - URL to the Catalogue search JSON endpoint + FINDING_AIDS_SEARCH_URL - URL to the Finding Aids search JSON endpoint + + GLOBAL_MESSAGE_URL - URL to the global alert message JSON endpoint + + CATALOGUE_SERVICES_API_BASE_URL - URL to the Catalogue Services API base URL + CATALOGUE_SERVICES_CLIENT - Catalogue Services realm client name + CATALOGUE_SERVICES_SECRET - Catalogue Services realm client secret + CATALOGUE_SERVICES_REALM - Catalogue Services realm name + + THUMBNAIL_SERVICE_API_BASE_URL - URL to the thumbnail service API base URL + + PATRON_UPGRADE_URL - URL to the Patron Upgrade service +
+ +## Setup + +1. Clone the app from GitHub. +2. Make sure you have MySQL running locally and configured in the `.env.development.local` config file. +3. Make sure you have Redis running locally and configured in the `.env.development.local` config file. +4. Make sure you have Solr running locally and configured in the `.env.development.local` config file.
💡️ If you are not planning on modifying the Solr index, you can point this at the devel or test environment Solr cluster. +5. `bin/setup` installs gems and performs database migrations for the `development` environment.
💡️ Gems are installed in `vendor/bundle`. + +## Running the app + +* `bin/run` runs the Rails server at http://localhost:3000. + * By default Rails will load the `development` environment. + * The runtime environment can be changed by defining `RAILS_ENV` before executing a command/script. e.g. + +```bash +RAILS_ENV=test bin/ci +``` + +## Tests + +* `bin/ci` contains all the tests and security vulnerability checks for the app. +* `tmp/test.log` will use the production logging format *NOT* the development one. +* The following test frameworks are used: + * [RSpec](https://rspec.info/) + * [Capybara](http://teamcapybara.github.io/capybara/) - simulates web application interaction + * [Webmock](https://github.com/bblimke/webmock) - HTTP request mocking and stubbing + +## Continuous Integration + +* CI is performed by [GitHub Actions](https://docs.github.com/en/actions). +* Workflows are defined in `.github/workflows`. + +### Releases + +Releases are automated via the `release.yml` GitHub workflow. This uses Google's +[release-please action](https://github.com/google-github-actions/release-please-action) to create a +release pull request when changes are pushed to the `main` branch. + +🚨 This release pull request will be updated with every merge to the `main` branch. + +🚨 It will bump the version automatically and create a release when it is merged. + +🚨 `CHANGELOG.md` is automatically created/updated for each release based on the commit messages. -* Configuration +Read more about how +[release-please](https://github.com/googleapis/release-please) works. -* Database creation +## Deployment -* Database initialization +* All runtime configuration should be supplied as environment variables. +* Rails logging uses [lograge](https://github.com/roidrage/lograge). `bin/setup help` can tell you how to see this locally. +* The temporary file directory configured by the `BLACKLIGHT_TMP_PATH` must be writable by the user that runs the application. +* Gems declared in the Gemfile are installed in the `vendor/bundle` directory. +* Rails assets must be precompiled before deployment and `RAILS_SERVE_STATIC_FILES` set to `true` in order for files in the `public` directory to be accessible. +* `RAILS_LOG_TO_STDOUT` must be set to `true` for logs to be sent to the console. -* How to run the test suite +## Linting, Static Analysis & Supply Chain Vulnerability Checking -* Services (job queues, cache servers, search engines, etc.) +The following tools provide linting, security and vulnerability checking of the code. -* Deployment instructions +* [rubocop](https://rubocop.org/) and [standardrb](https://github.com/testdouble/standard) ensure standardised code formatting and best practices. +* [brakeman](https://github.com/presidentbeef/brakeman) provides static analysis checking. + * Reports are written to `tmp/brakeman.html` +* [bundler-audit](https://github.com/rubysec/bundler-audit) checks application dependencies for security vulnerabilities. +* [strong-migrations](https://github.com/ankane/strong_migrations) catches unsafe migrations in development. -* ... +## License +The application is available as open source under the terms of the [Apache 2 License](https://opensource.org/licenses/Apache-2.0).