nypl/circ-webapp

Library Simplified 流通管理器

!https://github.com/nypl-simplified/circulation/actions/workflows/test.yml/badge.svg?branch=develop !GitHub发布

目录

• 概述
• Git分支工作流
• 开发
  • 安装
  • 操作
  • 测试
  • 代码更改
  • 向流通管理器管理界面添加馆藏
• 生成文档
• 持续集成
• 使用NewRelic运行
• 贡献
• 许可证
• 附录

概述

这是Library Simplified的流通管理器。流通管理器是图书馆馆藏与Library Simplified各种客户端应用（包括SimplyE）之间的主要连接点。它处理用户认证，将授权作品与开放获取内容相结合，从发行商API和次要来源获取更新的图书信息，并以适当组织的OPDS提要形式提供可用图书。

重要提示：SimplyE应用将于2025年8月停止使用，此处共享的资源也将停用。

Git分支工作流

默认分支是develop，这是用于分支修复错误或开发新功能的工作分支。功能分支的拉取请求合并到develop后，可以将更改合并到main以创建发布版本。

名称遵循<organization>-deploy-<env>模式的分支受到保护，用作指定组织的CI/CD流程的一部分。这些分支包括：

• nypl-deploy-qa
• nypl-deploy-production
• openebooks-deploy-qa
• openebooks-deploy-production
• bpl-deploy-qa
• bpl-deploy-production

开发

运行流通管理器实例的首选方法是通过Docker容器。如果由于某种原因无法运行容器化版本的流通管理器，可以在docs/NonDockerInstallation.md中找到直接安装的初始说明。

安装

获取本地开发环境的推荐方法是通过Docker。如果需要执行直接安装，请参阅非Docker安装文档。

注意：流通管理器容器应可在amd64和arm64架构的机器上构建和运行。但是，由于我们当前依赖的ElasticSearch容器化版本存在差异，在arm64机器（包括使用Apple M1芯片系列的机器）上编排集群需要使用不同的Docker Compose文件（docker-compose.arm64.yml）。如果使用下面的make命令控制本地集群，这种差异不会产生影响，因为它会根据机器的架构选择正确的compose文件。但是，如果在基于arm64的机器上直接运行docker-compose命令，请确保通过docker-compose --file docker-compose.arm64.yml <命令>使用正确的compose文件。

Docker

除了安装Docker Desktop（上面的链接），您还需要在[***] Hub获得。但是，Docker Engine只能代表经过身份验证的用户定位和拉取镜像。

创建账户后（或使用已有账户），您需要通过Docker Desktop安装登录。您应该可以从Docker Desktop仪表板窗口的右上角进行登录。

Make

提供了一个Makefile来帮助管理流通管理器的本地容器。如果您的系统上当前没有make，它应该可以从系统的包管理器（apt、brew等）获得。如果您无法安装或不想安装make本身，也可以通过手动复制并粘贴命令到shell中来运行Makefile中的命令。

克隆仓库并构建镜像

以下shell命令将克隆此仓库并为流通管理器Web应用程序和PostgreSQL数据库构建Docker镜像：

shell
git clone https://github.com/NYPL-Simplified/circulation.git
cd ./circulation
make build

为cron作业设置TZ

将环境变量TZ设置为您的本地时区。默认时区为America/New_York。

操作

成功构建镜像后，可以使用以下命令启动本地集群：

shell
make up

首次启动集群时，数据库容器将运行初始化脚本localdev_postgres_init.sh，该脚本创建开发和测试数据库，安装PostgreSQL扩展，并创建有凭据的用户。由于PostgreSQL数据目录持久化在Docker卷中，后续启动不会重新初始化数据库。Web应用容器将等待数据库可用并接受连接后才启动其Web服务器。如果您想观察初始化过程，请使用make up-watch而不是make up，以保持终端连接到运行中容器的输出。

如果您以前运行过容器化版本的流通管理器，可能会有一个Docker卷保留用于持久化PostgreSQL数据目录。如果是这种情况，并且该目录中的数据库配置不正确，make up-watch的输出可能如下所示：

Text
cm_local_db        | PostgreSQL Database directory appears to contain a database; Skipping initialization

[...]

cm_local_db        | 2021-11-19 22:20:06.563 UTC [74] FATAL:  password authentication failed for user "simplified"
cm_local_db        | 2021-11-19 22:20:06.563 UTC [74] DETAIL:  Role "simplified" does not exist.

[...]

cm_local_webapp    | --- Database unavailable, sleeping 5 seconds

如果出现这种情况，运行make clean删除现有卷，然后再次运行make up-watch——您应该会看到数据库初始化过程发生。

集群运行后（以及Web服务器启动后），您应该能够在http://localhost访问API端点，并在http://localhost/admin/访问管理Web应用。首次尝试登录管理应用时，将使用您提供的凭据创建用户。

其他生命周期管理命令（完整列表可通过make help获得）：

• make stop / make start - 运行make up后，您可以暂停和取消暂停集群而不销毁容器
• make down - 停止集群并删除容器和虚拟网络
• make clean - 停止集群，删除容器、虚拟网络和数据库卷
• make full-clean - 与make clean相同，但还会删除集群的Docker镜像

访问容器

集群运行时，可以使用以下命令访问容器：

• make db-session - 以超级用户身份在数据库容器上启动psql会话
• make webapp-shell - 在webapp容器上打开bash shell
• make webapp-py-repl - 在webapp容器上打开Python REPL会话，在项目的virtualenv中
• make scripts-shell - 在scripts容器上打开bash shell
• make scripts-py-repl - 在scripts容器上打开Python REPL会话，在项目的virtualenv中

测试

运行集群时，可以使用以下命令启动测试套件：

shell
make test

这将通过pytest运行整个测试套件。如果您希望使用pytest的-x选项在第一个错误或失败时退出，可以使用：

shell
make test-x

运行特定测试

您可以忽略Makefile，通过docker exec直接向webapp容器发出pytest命令，如下所示：

shell
docker exec -it cm_local_webapp pipenv run pytest tests

这使您能够访问pytest的所有标准选项，允许进行以下变体：

shell
# 使用-x快速失败
docker exec -it --env TESTING=1 cm_local_webapp /usr/local/bin/runinvenv /simplified_venv pytest -x tests

# 运行特定测试类
docker exec -it --env TESTING=1 cm_local_webapp /usr/local/bin/runinvenv /simplified_venv pytest tests/test_controller.py::TestCirculationManager

# 运行特定测试方法
docker exec -it --env TESTING=1 cm_local_webapp /usr/local/bin/runinvenv /simplified_venv pytest tests/test_controller.py::TestCirculationManager::test_exception_during_external_search_initialization_is_stored

# 关闭警告输出
docker exec -it --env TESTING=1 cm_local_webapp /usr/local/bin/runinvenv /simplified_venv pytest --disable-warnings tests

pytest可执行文件的完整选项集可在[***]

代码更改

Web应用和脚本运行器的本地开发Docker容器（分别为cm_local_webapp和cm_local_scripts）的虚拟化文件系统中没有代码库的副本。相反，此仓库检出到的本地目录作为只读绑定挂载提供给容器，位于/home/simplified/circulation。该绑定挂载的设置通过docker-compose进行，可以在docker-compose.yml和docker-compose.arm64.yml的webapp和scripts部分中看到。

由于这些主机挂载通过Docker Compose进行，如果您通过docker run直接从构建的镜像创建容器，除非通过命令行选项指定绑定挂载，否则它们将不存在，例如：

shell
docker run -d --rm --mount type=bind,source="$(pwd)",target=/home/simplified/circulation \
  --entrypoint tail circulation_webapp:latest -f /dev/null

通过将本地目录作为绑定挂载，您应该能够在主机机器上进行更改，并看到它们反映在容器的行为中。

向流通管理器管理界面添加馆藏

如果您正在处理流通管理器管理界面，并且需要向本地应用添加图书馆藏以进行测试，可以按照这些说明操作。

生成文档

使用Sphinx的代码文档可在此仓库的http://nypl-simplified.github.io/circulation/index.html%E4%B8%8A%E6%89%BE%E5%88%B0%E3%80%82%E5%AE%83%E7%9B%AE%E5%89%8D%E8%AE%B0%E5%BD%95%E4%BA%86%E6%AD%A4%E4%BB%93%E5%BA%93%E7%9A%84%60api%60%E7%9B%AE%E5%BD%95%E3%80%81%60scripts%60%E6%96%87%E4%BB%B6%E5%92%8C%60core%60%E5%AD%90%E6%A8%A1%E5%9D%97%E7%9B%AE%E5%BD%95%E3%80%82%E6%96%87%E6%A1%A3%E7%9A%84%E9%85%8D%E7%BD%AE%E5%8F%AF%E5%9C%A8%60/docs%60%E4%B8%AD%E6%89%BE%E5%88%B0%E3%80%82

Github Actions负责生成.rst源文件、生成HTML静态站点，并将构建部署到gh-pages分支。

要本地查看文档，请进入/docs目录并运行make html。这将生成.rst源文件并在/docs/build/html中构建静态站点。

使用Swagger(OpenAPI)的API文档可在/apidocs_admin和/apidocs_public端点找到。

持续集成

对于新的拉取请求以及合并到默认develop分支时，此项目通过Github Actions运行所有单元测试。相关文件可在.github/workflows/test.yml中找到。贡献更新或修复时，要求所有python 3环境的测试Github Action通过。推送更改前在本地运行tox命令，以确保在提交之前发现任何失败的测试。

如上所述，Github Actions还用于构建Sphinx文档并将其部署到Github Pages。相关文件可在.github/workflows/docks.yml中找到。

使用NewRelic运行

此代码库包括使用NewRelic为API和后台脚本提供工具的准备，用于错误监控、指标和其他目的。默认情况下，本地开发中禁用此功能，未经特定配置部署时也不会运行。以下步骤假设您已注册NewRelic账户并有权访问可用于为应用程序提供工具的API密钥。

要在通过docker compose本地运行时进行工具化，必须执行三个步骤：

1. 您的本地开发机器上必须运行NewRelic基础设施代理。这可以通过macOS上的brew或其他方式安装（参见NewRelic文档）
2. 必须在根目录中提供一个.env文件，其中包含以下行：NEW_RELIC_LICENSE_KEY=[your_newrelic_key_here]
3. 环境变量NEW_RELIC_MONITOR_MODE必须在您当前使用的docker compose文件中设置为'true'

要为部署的流通管理器实例提供工具化，必须向运行CM的docker容器提供以下环境变量作为运行时变量（如何执行取决于您的生产环境）：

• NEW_RELIC_APP_NAME：标识您的应用程序的字符串
• NEW_RELIC_MONITOR_MODE：格式为字符串的布尔值
• NEW_RELIC_CONFIG_FILE：配置文件的绝对路径，无需更改时应为/home/simplified/circulation/newrelic.ini
• NEW_RELIC_ENVIRONMENT：指定开发/qa/生产环境
• NEW_RELIC_LICENSE_KEY：您的NewRelic账户的API密钥

贡献

有关更多信息，请参见此处。

许可证

此项目是开源软件，根据Apache-2.0许可证授权。

附录

查看https://github.com/NYPL-Simplified/Simplified/wiki%E4%BA%86%E8%A7%A3%E6%9C%89%E5%85%B3%E6%B5%81%E9%80%9A%E7%AE%A1%E7%90%86%E5%99%A8%E5%90%84%E7%A7%8D%E4%B8%BB%E9%A2%98%E7%9A%84%E6%9B%B4%E6%B7%B1%E5%85%A5%E4%BF%A1%E6%81%AF%E3%80%82