Quepid

Quepid 使改进应用程序的搜索结果成为一个可重复、可靠的工程过程，整个团队都能理解。它解决了三个问题：

我们的协作糟糕 要在搜索方面取得全面进展，需要深入的跨职能协作。通过电子邮件或在电子表格中跟踪搜索需求是不够的。
搜索测试很困难 搜索变更是全面的：大多数变更都会引发问题。测试很困难：你不能在每次相关性变更后运行数百次搜索。
迭代速度慢 前进似乎是不可能的。为了避免倒退，进展缓慢。许多人干脆放弃搜索，剥夺了用户查找关键信息的手段。

要了解更多信息，请查看 Quepid 网站和 Quepid wiki。

如果你准备立即开始使用，可以现在就使用 Hosted Quepid 服务，或者按照安装步骤设置你自己的 Quepid 实例。

开发设置

I. 系统依赖

使用 Docker Compose

从已构建的机器配置大约需要 3-4 分钟。从头开始配置大约需要 20 分钟。

1. 前提条件

确保你已安装 Docker。前往 https://www.docker.com/community-edition#/download 获取安装说明。并启动 Docker 应用程序。

要使用 brew 安装，请按以下步骤操作：

brew cask install docker
brew cask install docker-toolbox

注意： 第一次尝试时，你可能会收到有关信任 Oracle 的警告。打开系统偏好设置 > 安全性和隐私，点击允许 Oracle 按钮，然后再次尝试安装 docker-toolbox。

2. 设置环境

运行本地 Ruby 设置脚本来设置 Docker 镜像：

bin/setup_docker

如果你想创建包含数百或数千个查询的案例，请执行以下操作：

 bin/docker r bundle exec thor sample_data:large_data

这对于对 Quepid 进行压力测试很有用！特别是对前端应用程序！

最后，要运行 Jupyter notebooks，你需要运行：

bin/setup_jupyterlite

3. 运行应用

现在在 http://localhost 本地启动 Quepid：

bin/docker server

服务器可能需要长达一分钟的时间才能响应，因为它在第一次调用时会编译所有前端资产。我们创建了一个辅助脚本来通过 Docker 运行和管理应用程序，该脚本封装了 docker-compose 命令。你需要安装 Ruby。你仍然可以直接使用 docker-compose，但对于基本操作，你可以使用以下命令：

启动应用：bin/docker server 或 bin/docker s
使用 bash 连接到应用容器：bin/docker bash 或 bin/docker ba
连接到 Rails 控制台：bin/docker console 或 bin/docker c
运行任意命令：bin/docker run [命令] 或 bin/docker r [命令]
以守护进程模式运行开发模式：bin/docker daemon 或 bin/docker q
销毁 Docker 环境：bin/docker destroy 或 bin/docker d
运行前端单元测试：bin/docker r rails test:frontend
运行后端单元测试：bin/docker r rails test

II. 开发日志

在 foreman 下运行应用时，你只能看到请求日志。要查看更详细的日志，请运行以下命令：

tail -f log/development.log

III. 运行测试

你可以运行三种类型的测试：

Minitest

这些测试运行 Rails 端的测试（主要是 API 控制器和模型）：

bin/docker r rails test

运行单个测试文件：

bin/docker r rails test test/models/user_test.rb

甚至可以通过传入行号来运行测试文件中的单个测试！

bin/docker r rails test test/models/user_test.rb:33

如果需要重置测试数据库设置，请运行：

bin/docker r bin/rake db:drop RAILS_ENV=test
bin/docker r bin/rake db:create RAILS_ENV=test

要查看测试过程中生成的日志，请在 test.rb 中设置 config.log_level = :debug，然后通过以下命令查看日志文件：

tail -f log/test.log

JS 语法检查

检查 JS 语法：

bin/docker r rails test:jshint

Karma

运行 Angular 端的测试。Karma 测试有两种模式：

单次运行：bin/docker r rails karma:run
持续/监视运行：bin/docker r bin/rake karma:start

注意： Karma 测试需要预编译资源，这会显著增加测试运行时间。如果你只修改了测试/规格文件，建议在监视模式下运行测试（bin/docker r bin/rake karma:start）。需要注意的是，每当你修改应用文件时，都需要重启进程（或使用单次运行模式）。

Rubocop

检查 Ruby 语法：

bin/docker r bundle exec rubocop

Rubocop 通常可以通过 --autocorrect-all 自动修正许多语法问题：

bin/docker r bundle exec rubocop --autocorrect-all

如果有新的我们不喜欢的"Cop"（他们称之为规则），你可以将其添加到 ./rubocop.yml 文件中。

所有测试

如果你想一次运行所有测试（例如在提交和推送之前），只需运行以下两个命令：

bin/docker r rails test
bin/docker r rails test:frontend

由于某些原因，我们无法用一个命令运行两者，尽管我们应该能做到！

性能测试

如果你想为用户创建大量查询进行测试，请运行

bin/docker r bin/rake db:seed:large_cases

你将有两个用户，quepid+100sOfQueries@o19s.com 和 quepid+1000sOfQueries@o19s.com 可供测试。

Notebook 测试

如果你想测试 Jupyterlite notebooks，或使用"真实"的案例和书籍，请运行

bin/docker r bundle exec thor sample_data:haystack_party

你将有大量来自 Haystack 评分派对书籍和案例的用户数据可供使用。这些数据来源于公共案例 https://app.quepid.com/case/6789/try/12?sort=default 和 https://app.quepid.com/books/25

IV. 调试

调试 Ruby

调试 Ruby 通常取决于具体情况，最简单的方法是将对象打印到 STDOUT：

puts object         # 打印对象的 .to_s 方法
puts object.inspect # 检查对象并打印（包括属性）
pp object           # 美化打印检查后的对象（类似 .inspect 但更好）

在 Rails 应用中，你可以使用日志记录器进行输出：

Rails.logger object.inspect

如果这还不够，你想运行调试器，可以使用包含的 debug gem。参见 https://guides.rubyonrails.org/debugging_rails_applications.html#debugging-with-the-debug-gem。

此外，我们还有 derailed gem 可用，它可以帮助你了解内存问题。

bin/docker r bundle exec derailed bundle:mem

调试 JS

在运行应用程序时，你可以使用你喜欢的工具以你一贯的方式调试 JavaScript。

JavaScript 文件将使用 Rails 资产管道合并成一个文件。

你可以通过在 config/environments/development.rb 中切换以下标志来关闭它：

# config.assets.debug = true
config.assets.debug = false

改为：

config.assets.debug = true
# config.assets.debug = false

由于此应用程序中有太多 Angular JS 文件，在 debug 模式下 Rails 会尝试单独加载每个文件，这会减慢应用程序速度，并在开发模式下等待脚本加载变得非常烦人。这就是为什么默认情况下它被关闭。

注意： 更改配置时不要忘记重启服务器。

另请注意，secure.js、application.js 和 admin.js 文件用于通过 Rails 资产管道加载所有 JavaScript 和 CSS 依赖项。如果你正在调试 Bootstrap，那么你需要单独的文件。因此，将 //= require sprockets 替换为 //= require bootstrap-sprockets。

Webpacker

要使用 webpacker（它会将 JavaScript 代码编译成包并更快地加载更改），你需要

bin/rails webpacker:install

在此之前我必须安装:

brew install mysql

调试 Splainer 和其他 NPM 包

可以将 docker-compose.override.yml.example 复制为 docker-compose.override.yml，并用它来覆盖环境变量或在开发期间使用 docker-compose.yml 中定义的 splainer-search JS 库的本地副本。示例已包含在内。只需用你的本地检出更新 splainer-search 的路径即可！https://docs.docker.com/compose/extends/

便利脚本

这个应用程序有两种运行脚本的方式: rake 和 thor。

Rake 非常适合依赖于应用程序环境的简单任务，以及 Rails 默认附带的默认任务。

而 Thor 是一个更强大的工具，用于编写比 Rake 更优雅地接受参数的脚本。

Rake

要查看可用的 rake 任务，请运行:

bin/docker r bin/rake -T

注意: 使用 bin/rake 确保运行的 rake 版本是与应用程序的 Gemfile.lock 锁定的版本(以避免与系统上可能安装的其他版本发生冲突)。这等同于 bundle exec rake。

你可能会使用的常见 rake 任务:

# 数据库
bin/docker r bin/rake db:create
bin/docker r bin/rake db:drop
bin/docker r bin/rake db:migrate
bin/docker r bin/rake db:rollback
bin/docker r bin/rake db:schema:load
bin/docker r bin/rake db:seed
bin/docker r bin/rake db:setup

# 显示路由
bin/docker r bin/rails routes

# 测试
bin/docker r rails test
bin/docker r rails test:frontend
bin/docker r bin/rake test:jshint

Thor

要查看可用的任务:

bin/docker r bundle exec thor list

更多文档请参见 Operating Documentation。

Elasticsearch

你需要配置 Elasticsearch 以接受来自浏览器的请求，使用 CORS。要启用 CORS，请将以下内容添加到 elasticsearch 的配置文件中。通常，这个文件位于 elasticsearch 可执行文件附近的 config/elasticsearch.yml。

http.cors:
  enabled: true
  allow-origin: /https?:\/\/localhost(:[0-9]+)?/

开发杂项

我想使用一个新的 Node 模块，或更新现有的模块

通常你只需执行:

bin/docker r yarn add foobar

或

bin/docker r yarn upgrade foobar

这将安装/升级 Node 模块，然后将该依赖保存到 package.json。

然后提交更新后的 package.json 和 yarn.lock 文件。

使用 bin/docker r yarn outdated 查看可以更新的包！

我想使用一个新的 Ruby Gem，或更新现有的 Gem

通常你只需执行:

bin/docker r bundle add foobar

这将安装新的 Gem，然后将该依赖保存到 Gemfile。

你也可以通过以下方式升级 Gemfile 中没有指定版本的 gem:

bin/docker r bundle update foobar

你可以通过以下方式移除 gem:

bin/docker r bundle remove foobar

然后提交更新后的 Gemfile 和 Gemfile.lock 文件。为了保险起见，运行 bin/setup_docker。

要了解你是否有过期的 gem，运行:

bin/docker r bundle outdated --groups

如何测试在域名下嵌套 Quepid

在 docker-compose.yml 中取消注释设置 - RAILS_RELATIVE_URL_ROOT=/quepid-app，然后打开 http://localhost:3000/quepid-app。

我想运行和测试本地 PRODUCTION 构建

以下步骤应该能让你在本地运行 Quepid 的生产构建(而不是开发构建)。

对代码进行所需的更改
从项目根目录运行以下命令来构建新的 docker 镜像:

docker build -t o19s/quepid -f Dockerfile.prod .

首次运行可能会出错。如果发生这种情况，请重试

为你的镜像标记一个新版本。
你可以硬编码你的版本或使用系统变量(如 QUEPID_VERSION=10.0.0)，或者如果你喜欢，使用 'latest'

docker tag o19s/quepid o19s/quepid:$QUEPID_VERSION

启动 mysql 容器

docker-compose up -d mysql

运行初始化脚本。这可能需要几秒钟

docker-compose run --rm app bin/rake db:setup

通过更新 app 的镜像版本来更新你的 docker-compose.prod.yml 文件 image: o19s/quepid:10.0.0
以守护进程(-d)或活动容器的方式启动应用

docker-compose up [-d]

你应该能够通过 http://localhost 访问应用

我想测试 SSL

.ssl 目录包含用于 SSL 的密钥和证书文件。这是一个仅用于开发的自签名生成的证书！

密钥/证书是使用以下命令生成的:

openssl req -new -newkey rsa:2048 -sha1 -days 365 -nodes -x509 -keyout .ssl/localhost.key -out .ssl/localhost.crt

注意: 不需要再次执行此操作。

docker-compose.yml 文件包含一个使用这些证书的 nginx 反向代理。你可以通过 https://localhost 或 http://localhost 访问 Quepid。(Quepid 仍然可以通过 80 端口的 http 访问。)

我想测试 OpenID 认证

在这里添加开发文档！

开发部署的 Keycloak 管理控制台凭据是 admin 和 password。

修改数据库

以下是生成迁移的示例:

bin/docker r bundle exec bin/rails g migration FixCuratorVariablesTriesForeignKeyName

接着运行 bin/docker r bundle exec rake db:migrate

当你更改了数据库模式时,还应该通过运行 bin/docker r bundle exec annotations 来更新模式注释数据。

更新 RubyGems

修改 Gemfile 文件,然后运行:

bin/docker r bundle install

你会看到更新后的 Gemfile.lock,继续检查它和 Gemfile 并提交到 Git。

前端是如何工作的?

我们在前端使用 Angular 1,作为其中的一部分,我们使用 angular-ui-bootstrap 包来实现所有的 UI 组件。这个包与 Bootstrap 3 版本绑定。我们通过 bootstrap.css 文件直接导入 Bootstrap 3 CSS。

对于各种管理页面,我们实际上使用的是 Bootstrap 5!它是通过 package.json 使用 NPM 引入的。参见 admin.js 中的 //= require bootstrap/dist/js/bootstrap.bundle 行,这里是我们引入它的地方。

我们目前使用 Rails Sprockets 来编译所有内容,但也有计划将 JavaScript 迁移到 Webpacker。

字体

aller 字体来自 FontSquirrel,并将 .ttf 转换为 .woff2 格式。

我想开发 Jupyterlite

运行 ./bin/setup_jupyterlite 来更新 ./jupyterlite/notebooks.gz 存档文件。这也会在 ./public/notebooks 目录中设置静态文件。但是,为了不在 Github 中检入数百个文件,我们忽略了该目录。在 asset:precompile 时,我们会解压 ./jupyterlite/notebooks.gz 文件。这在 Heroku 和生产 Docker 镜像中都可以正常工作。

要更新 Jupyterlite 的版本,请编辑 Dockerfile.dev 和 Dockerfile.prod 并更新 pip install 的版本。

问题?Jupyterlite 在本地主机上可以工作吗????

个人访问令牌是如何工作的?

参见这篇很棒的博客文章:https://keygen.sh/blog/how-to-implement-api-key-authentication-in-rails-without-devise/。

质量保证

有一个代码部署流程到 http://quepid-staging.herokuapp.com 网站,在成功提交到 main 分支后运行。

如果你有待处理的迁移,你需要通过以下方式运行它们:

heroku run bin/rake db:migrate -a quepid-staging
heroku restart -a quepid-staging

种子数据

以下账户是通过 bin/setup_docker 过程创建的。它们都遵循以下格式:

email: quepid+[类型]@o19s.com
password: password

其中类型是以下之一:

admin: 管理员账户
realisticActivity: 一个拥有各种案例的用户,展示了 Quepid,包括 Haystack Rating Party 演示案例和书籍,并且是 'OSC' 团队的成员。
100sOfQueries: 一个拥有数百个查询的 Solr 案例的用户(通常被禁用)
1000sOfQueries: 一个拥有数千个查询的 Solr 案例的用户(通常被禁用)
oscOwner: 拥有 'OSC' 团队的用户
oscMember: 'OSC' 团队成员的用户