{"id":24093254,"url":"https://github.com/umd-lib/reciprocal-borrowing","last_synced_at":"2025-02-27T10:47:45.143Z","repository":{"id":12799441,"uuid":"72848116","full_name":"umd-lib/reciprocal-borrowing","owner":"umd-lib","description":"Big Ten Academic Alliance Reciprocal Borrowing application","archived":false,"fork":false,"pushed_at":"2024-11-18T15:06:44.000Z","size":152,"stargazers_count":0,"open_issues_count":0,"forks_count":3,"subscribers_count":13,"default_branch":"main","last_synced_at":"2025-01-10T09:26:22.853Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/umd-lib.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2016-11-04T13:01:26.000Z","updated_at":"2024-11-18T14:07:52.000Z","dependencies_parsed_at":"2024-02-20T02:24:48.986Z","dependency_job_id":"7a5614f2-4047-41fb-985a-af1a8f9e7372","html_url":"https://github.com/umd-lib/reciprocal-borrowing","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Freciprocal-borrowing","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Freciprocal-borrowing/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Freciprocal-borrowing/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/umd-lib%2Freciprocal-borrowing/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/umd-lib","download_url":"https://codeload.github.com/umd-lib/reciprocal-borrowing/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241005368,"owners_count":19892780,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-10T09:26:38.870Z","updated_at":"2025-02-27T10:47:45.111Z","avatar_url":"https://github.com/umd-lib.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# reciprocal-borrowing\n\nThis Rails application is designed to work with Shibboleth and the\n[InCommon][incommon] identity management federation to verify patron eligibility\nfor [reciprocal borrowing][btaa_reciprocal_borrowing] between members of the\n[Big Ten Academic Alliance][btaa].\n\nReciprocal Borrowing is different from other UMD/SSDR Rails applications:\n\n1) It does not use a database\n\n2) It does not utilize the following Rails components:\n\n* ActiveRecord\n* ActiveStorage\n* ActionMailer\n* ActionMailbox\n* ActionText\n* ActionCable\n\n3) It does not use the “umd-lib/umd_lib_style”\n   (\u003chttps://github.com/umd-lib/umd_lib_style\u003e) gem for styling.\n\n4) It uses Sprockets (\u003chttps://github.com/rails/sprockets\u003e) for the asset\n   pipeline (as opposed to “webpacker\")\n\n## Quick Start\n\nFor local development, this application can be used in conjunction with a\nDocker-based Shibboleth Identity Provider (IdP) and Shibboleth Service Provider\n(SP) provided in the [umd-lib/reciprocal-borrowing-dev-env][dev-env] GitHub\nrepository. Refer to the README.md file in that repository for setup\ninstructions.\n\n### \"development_docker\" Environment\n\nAn additional \"development_docker\" environment has been added to the\nRails standard \"development\", \"test\", and \"production\" environments, to support\nrunning in the \"umd-lib/reciprocal-borrowing-dev-env\" Docker stack.\n\nThis environment contains:\n\n* changes to use the \"borrow-local\" hostname\n* changes to the \"shibboleth_config.yml\" file so that all organizations use the\n  Shibboleth IdP in the Docker stack\n* modifications to support running on M-series (Apple Silicon) laptops\n* Values for the environment variables in the \".env\" file\n\n## Application Functionality\n\nThis application must be added to a server acting as a Shibboleth Service\nProvider (SP). In order to be used in a production environment, the SP must be\nregistered with [InCommon][incommon].\n\nThe functionality of this application is extremely straightforward:\n\n1) The home page provides a list of organizations participating in reciprocal\n   borrowing. On this page, the organization doing the lending is selected.\n\n2) After selecting the lending organization, a second page is shown with a\n   list of organizations. The authenticating organization (the organization the\n   borrowing patron is a member of) is selected. After selecting the\n   organization, the application redirects the browser (via an entityID provided\n   to the Shibboleth SP running on the server) to a Shibboleth IdP for the\n   selected organization.\n\n3) The borrowing patron authenticates via their organizational authentication\n   process.\n\n   **Note:** This step takes place entirely outside of this application, so this\n   application never has access to the patron's credentials.\n\n4) After successfully authenticating, the browser is redirected back to this\n   application, which indicates whether the patron is eligible to borrow.\n\n**Note:** When running on the dev, stage, or production servers, there is no\nknown way to show that a user in ineligible for borrowing because the UMD server\nalways seems pass back the expected property.\n\n### Transactions Logging\n\nThe \"transactions.log\" file contains the results of *completed* authentications,\nin which the user was successfully authenticated.\n\nEach line in the \"transactions.log\" file has the following form:\n\n```text\n[\u003cTIMESTAMP\u003e] \u003cIDENTIFIER\u003e,lending_org_code=\u003cLENDING_ORG\u003e,auth_org_code=\u003cAUTH_ORG\u003e,authorized=[true|false]\n```\n\nwhere:\n\n* \\\u003cTIMESTAMP\u003e: The date/time of the completed authentication\n* \\\u003cIDENTIFIER\u003e: The \"eduPersonTargetedID\" attribute returned by Shibboleth, or\n  \"N/A\" if it is not provided. As described in\n  \u003chttps://wiki.refeds.org/display/STAN/eduPerson+2020-01#eduPerson202001-eduPersonTargetedID\u003e\n  it is a \"A persistent, non-reassigned, opaque identifier for a principal.\"\n* \\\u003cLENDING_ORG\u003e: The code (from \"config/shibboleth_config.yml\") of the lending\n  organization\n* \\\u003cAUTH_ORG\u003e: The code (from \"config/shibboleth_config.yml\") of the\n  organization used to authenticate the user.\n\nIf \"authorized\" is \"true\", the user is authorized to borrow, if \"false\" the\nuser is not.\n\n## Application Configuration\n\nThe \"config/shibboleth_config.yml\" file contains the configuration information\nfor the organizations participating in reciprocal borrowing, and has been\npre-populated with Big Ten Academic Alliance members. The file contains\ndifferent sections for the \"production\", \"development\", \"development_docker\",\nand \"test\" environments.\n\nThe application should work \"out of the box\" when used in conjunction with the\n[umd-lib/reciprocal-borrowing-dev-env][dev-env] GitHub repository, in a\n\"development_docker\" Rails environment. The \"development_docker\" section of the\nshibboleth_config.yml has been pre-configured so that \"idp_entity_id\" for all\norganizations points to the Docker IdP.\n\nFor a \"production\" environment, the shibboleth_config.yml file has been\npre-populated \"idp_entity_id\" values derived from the InCommon metadata for\nthose organizations. Note that these values will only work when running from an\nSP registered with InCommon.\n\n## Dockerfile\n\nThe \"Dockerfile\" (and associated \"docker_config\" directory) for creating the\nDocker image are intended for use with the\n[umd-lib/k8s-reciprocal-borrowing][k8s-rb] Kubernetes configuration.\n\nThe Dockerfile combines the following applications into a single Docker image:\n\n* Apache HTTPD web server\n* Shibboleth Service Provider (Shibboleth SP)\n* Passenger Phusion app server\n* The Reciprocal Borrowing Rails application\n\nCombining all these applications is necessary because:\n\n* The Shibboleth Service Provider runs as a separate process, but communicates\n  with Apache via an Apache module (see\n  \u003chttps://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2065335062/Apache\u003e)\n\n* Phusion Passenger is integrated with Apache as a module\n  (see “Apache integration mode” in\n  \u003chttps://www.phusionpassenger.com/docs/advanced_guides/in_depth/ruby/integration_modes.html\u003e).\n  This is necessary because the Shibboleth Service Provider stores the\n  Shibboleth attributes received from the Shibboleth IdP as Apache “per-request”\n  environment variables (see \u003chttps://httpd.apache.org/docs/2.4/env.html\u003e) and\n  the only way that the Reciprocal Borrowing application can access them is via\n  environment variables set by Phusion Passenger (which as a module, has access\n  to the Apache “per-request” environment variables).\n\n* Phusion Passenger is responsible for starting the Reciprocal Borrowing\n  application, so it is not necessary to start it as a separate process.\n\n**Note:** Shibboleth attributes could be passed to the Reciprocal Borrowing\napplication from Apache via HTTP request headers, which would remove the need for\nPhusion Passenger, and allow the Reciprocal Borrowing application to run in\na separate container. This method, however, appears to be strongly discouraged\nby Shibboleth (see \u003chttps://shibboleth.atlassian.net/wiki/spaces/SP3/pages/2065335257/AttributeAccess\u003e).\n\n## Building the Docker Image for K8s Deployment\n\nThe following procedure uses the Docker \"buildx\" functionality and the\nKubernetes \"build\" namespace to build the Docker image. This procedure should\nwork on both \"arm64\" and \"amd64\" MacBooks.\n\nThe image will be automatically pushed to the Nexus.\n\n### Local Machine Setup\n\nSee \u003chttps://github.com/umd-lib/k8s/blob/main/docs/DockerBuilds.md\u003e in\nGitHub for information about setting up a MacBook to use the Kubernetes\n\"build\" namespace.\n\n### Creating the Docker image\n\n1) In an empty directory, checkout the Git repository and switch into the\n   directory:\n\n    ```bash\n    $ git clone git@github.com:umd-lib/reciprocal-borrowing.git\n    $ cd reciprocal-borrowing\n    ```\n\n2) Checkout the appropriate Git tag, branch, or commit for the Docker image.\n\n3) Set up an \"APP_TAG\" environment variable:\n\n    ```bash\n    $ export APP_TAG=\u003cDOCKER_IMAGE_TAG\u003e\n    ```\n\n   where \\\u003cDOCKER_IMAGE_TAG\u003e is the Docker image tag to associate with the\n   Docker image. This will typically be the Git tag for the application version,\n   or some other identifier, such as a Git commit hash. For example, using the\n   Git tag of \"1.2.0\":\n\n    ```bash\n    $ export APP_TAG=1.2.0\n    ```\n\n4) Switch to the Kubernetes \"build\" namespace:\n\n    ```bash\n    $ kubectl config use-context build\n    ```\n\n5) Create the \"docker.lib.umd.edu/reciprocal-borrowing\" Docker image:\n\n    ```bash\n    $ docker buildx build --no-cache --platform linux/amd64 --push --no-cache \\\n        --builder=kube  -f Dockerfile -t docker.lib.umd.edu/reciprocal-borrowing:$APP_TAG .\n    ```\n\n   The Docker image will be automatically pushed to the Nexus.\n\n## Environment Configuration (Local Development)\n\nThe application uses the \"dotenv\" gem to configure the application environment.\nA sample \"env_example\" file has been provided to assist with this process.\n\nThe \"env_example\" file is mainly for documenting the necessary and optional\nenvironment variables. Creating a \".env\" file when using the\n\"umd-lib/reciprocal-borrowing-dev-env\" GitHub repository is not necessary\nas the relevant configuration is already in place in the\n`config/environments/development_docker.rb` file.\n\nIn the production environment, the appropriate environment variables are\nprovided in the container environment by the \"umd-lib/k8s-reciprocal-borrowing\"\nKubernetes configuration.\n\n## Environment Banner\n\nIn keeping with SSDR policy, an \"environment banner\" will be displayed at the\ntop of each page when running on non-production servers.\n\nBy default, in the local development environment (determined by\n`Rails.env.development?`returning `true`), a \"Local Environment\" banner will be\ndisplayed.\n\nOn non-production servers, the environment banner can be configured using the\nfollowing environment variables:\n\n* ENVIRONMENT_BANNER - the text to display in the banner\n* ENVIRONMENT_BANNER_FOREGROUND - the foreground color for the banner, as a CSS color\n* ENVIRONMENT_BANNER_BACKGROUND - the background color for the banner, as a CSS color\n* ENVIRONMENT_BANNER_ENABLED - (optional) \"false\" (case-sensitive) disables the\n  banner. Anything else (including blank, or not providing the variable) enables\n  the banner.\n\nSample configuration for an environment banner displaying\n\"Example Banner Environment\" on a blue background with orange text:\n\n```text\nENVIRONMENT_BANNER_ENABLED=true\nENVIRONMENT_BANNER_BACKGROUND=\"#0000ff\"\nENVIRONMENT_BANNER_FOREGROUND=\"#ffa500\"\nENVIRONMENT_BANNER=Example Banner Environment\n```\n\n## License\n\nSee the [LICENSE](LICENSE.md) file for license rights and limitations\n(Apache 2.0).\n\n---\n[btaa]: https://www.btaa.org/\n[btaa_reciprocal_borrowing]: https://btaa.org/library/programs-and-services/reciprocal-borrowing\n[dev-env]: https://github.com/umd-lib/reciprocal-borrowing-dev-env\n[k8s-rb]: https://github.com/umd-lib/k8s-reciprocal-borrowing\n[incommon]: https://www.incommon.org/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumd-lib%2Freciprocal-borrowing","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fumd-lib%2Freciprocal-borrowing","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fumd-lib%2Freciprocal-borrowing/lists"}