Quepid 讓改進應用程式的搜尋結果成為整個團隊都能理解的可重複、可靠的工程過程。它涉及三個問題:
我們的合作很糟糕要在搜尋領域取得全面進展需要深入的跨職能合作。發送電子郵件或在電子表格中追蹤搜尋要求並不能解決問題。
搜尋測試很困難搜尋變更是跨領域的:大多數變更都會導致問題。測試很困難:您無法在每次相關性變更後執行數百次搜尋。
迭代緩慢向前推進似乎是不可能的。為了避免倒退,進展緩慢。許多人乾脆放棄搜索,剝奪了用戶查找關鍵資訊的手段。
要了解更多信息,請查看 Quepid 網站和 Quepid wiki。
如果您已準備好立即投入使用,則可以立即使用託管 Quepid 服務或依照安裝步驟設定您自己的 Quepid 實例。
以下是與開發 Quepid 開源專案相關的信息,主要面向有興趣擴展 Quepid 功能的人!
從已建置的電腦進行配置大約需要 3 - 4 分鐘。從頭開始配置大約需要 20 分鐘。
確保您已經安裝了 Docker。請到此處 https://www.docker.com/community-edition#/download 以了解安裝說明。 Docker 應用程式已啟動。
若要使用brew安裝,請依照下列步驟操作:
brew cask install docker
brew cask install docker-toolbox
注意:第一次嘗試時您可能會收到有關信任 Oracle 的警告。開啟系統偏好設定 > 安全性和隱私,按一下允許 Oracle 按鈕,然後再次嘗試安裝 docker-toolbox
執行基於 Ruby 的本機設定腳本來設定 Docker 映像:
bin/setup_docker
如果您想建立一些具有 100 和 1000 次查詢的案例,請執行以下操作:
bin/docker r bundle exec thor sample_data:large_data
這對於壓力測試 Quepid 很有用!尤其是前端應用!
最後,要運行 Jupyter 筆記本,您需要運行:
bin/setup_jupyterlite
現在在 http://localhost 上本地啟動 Qupid:
bin/docker server
伺服器可能需要一分鐘的時間才能回應,因為它會在第一次呼叫時編譯所有前端資源。
我們創建了一個幫助程式腳本來透過 docker 運行和管理應用程序,該腳本包含docker-compose
命令。您需要安裝 Ruby。您仍然可以直接使用docker compose
,但對於基本內容,您可以使用以下命令:
bin/docker server
或bin/docker s
bin/docker bash
或bin/docker ba
bin/docker console
或bin/docker c
bin/docker run [COMMAND]
或bin/docker r [COMMAND]
bin/docker daemon
或bin/docker q
bin/docker destroy
或bin/docker d
bin/docker r rails test:frontend
bin/docker r rails test
在 foreman 下執行應用程式時,您只會看到請求日誌,有關更詳細的日誌記錄,請執行以下命令:
tail -f log/development.log
您可以執行三種類型的測試:
這些測試從 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
查看測試期間產生的日誌 set config.log_level = :debug
在test.rb
中,然後透過以下方式尾部日誌檔案:
tail -f log/test.log
檢查 JS 語法:
bin/docker r rails test:jshint
運行 Angular 端的測試。業力測試有兩種模式:
bin/docker r rails karma:run
bin/docker r bin/rake karma:start
注意: karma 測試需要預先編譯資產,這會增加測試運行的大量時間。如果您僅對測試/規範檔案進行更改,則建議您在監視模式下執行測試( bin/docker r bin/rake karma:start
)。需要注意的是,每當您對應用程式檔案進行更改時,都必須重新啟動該進程(或使用單次運行模式)。
要檢查 Ruby 語法:
bin/docker r bundle exec rubocop
Rubocop 通常可以透過--autocorrect-all
自動修正遇到的許多 lint 問題:
bin/docker r bundle exec rubocop --autocorrect-all
如果有一個我們不喜歡的新「警察」規則,您可以將其新增至./rubocop.yml
檔案。
如果您想一次執行所有測試(例如在提交和推送之前),只需執行以下兩個命令:
bin/docker r rails test
bin/docker r rails test:frontend
由於某種原因,我們不能用一個命令同時運行這兩個命令,儘管我們應該可以! 。
如果您想為用戶建立大量查詢以進行測試,請執行
bin/docker r bin/rake db:seed:large_cases
您將有兩個使用者[email protected]
和[email protected]
進行測試。
如果您想測試 Jupyterlite 筆記本,或使用「真實」案例和書籍,請執行
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
調試ruby通常要根據情況而定,最簡單的方法是將物件列印到STDOUT:
puts object # Prints out the .to_s method of the object
puts object . inspect # Inspects the object and prints it out (includes the attributes)
pp object # Pretty Prints the inspected object (like .inspect but better)
在 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
運行應用程式時,您可以使用您最喜歡的工具來調試 javascript,就像您一直這樣做的方式一樣。
javascript 檔案將使用rails asset pipeline 連接成一個檔案。
您可以透過在config/environments/development.rb
中切換以下標誌來關閉它:
# config.assets.debug = true
config . assets . debug = false
到
config . assets . debug = true
# config.assets.debug = false
因為這個應用程式中有太多的 Angular JS 文件,並且在debug
模式下 Rails 會嘗試單獨加載每個文件,這會減慢應用程式的速度,並且在開發模式下等待腳本加載變得非常煩人。這就是它預設關閉的原因。
PS:更改配置後不要忘記重新啟動伺服器。
另請注意,檔案secure.js
、 application.js
和admin.js
用於透過 Rails Asset 管道載入所有 JavaScript 和 CSS 依賴項。如果您正在偵錯 Bootstrap,那麼您將需要單獨的檔案。因此,將//= require sprockets
替換為//= require bootstrap-sprockets
。
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 任務可用,請執行:
bin/docker r bin/rake -T
注意:使用bin/rake
可確保正在執行的rake
版本是鎖定到應用程式Gemfile.lock
的版本(以避免與系統上可能安裝的其他版本發生衝突)。這相當於bundle exec rake
。
您可能使用的常見 rake 任務:
# db
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
# show routes
bin/docker r bin/rails routes
# tests
bin/docker r rails test
bin/docker r rails test:frontend
bin/docker r bin/rake test:jshint
查看可用任務:
bin/docker r bundle exec thor list
其他文檔位於操作文檔中。
您需要設定 Elasticsearch 以使用 CORS 接受來自瀏覽器的請求。若要啟用 CORS,請將以下內容新增至 elasticsearch 的設定檔中。通常,此檔案位於config/elasticsearch.yml
中的 elasticsearch 可執行檔附近。
http.cors :
enabled : true
allow-origin : /https?://localhost(:[0-9]+)?/
在 wiki 上查看更多詳細資訊:https://github.com/o19s/quepid/wiki/Troubleshooting-Elasticsearch-and-Quepid
通常你會簡單地做:
bin/docker r yarn add foobar
或者
bin/docker r yarn upgrade foobar
這將安裝/升級 Node 模組,然後將該依賴項儲存到package.json
。
然後簽入更新的package.json
和yarn.lock
檔案。
使用bin/docker r yarn outdated
來查看可以更新哪些軟體包!
通常你會簡單地做:
bin/docker r bundle add foobar
這將安裝新的 Gem,然後將該依賴項儲存到Gemfile
。
您也可以透過以下方式升級Gemfile
中沒有特定版本的 gem:
bin/docker r bundle update foobar
您可以透過以下方式刪除寶石:
bin/docker r bundle remove foobar
然後簽入更新的Gemfile
和Gemfile.lock
檔。為了更好地衡量,運行bin/setup_docker
。
要了解您是否有過期的 gem,請運行:
bin/docker r bundle outdated --groups
取消docker-compose.yml
中設定的註解- RAILS_RELATIVE_URL_ROOT=/quepid-app
,然後開啟 http://localhost:3000/quepid-app。
這些步驟應該讓您在本機啟動並執行 Quepid 的生產版本(相對於開發人員版本)。
docker build -t o19s/quepid -f Dockerfile.prod .
第一次運行時可能會出錯。如果發生這種情況,請重試
docker tag o19s/quepid o19s/quepid:$QUEPID_VERSION
docker compose up -d mysql
docker compose run --rm app bin/rake db:setup
透過更新應用程式image: o19s/quepid:10.0.0
將應用程式作為守護程式 (-d) 或活動容器啟動
docker compose up [-d]
有一個目錄.ssl
,其中包含用於 SSL 的金鑰和憑證檔案。這是一個自簽名產生的證書,僅供開發使用!
密鑰/證書是使用以下命令產生的:
openssl req -new -newkey rsa:2048 -sha1 -days 365 -nodes -x509 -keyout .ssl/localhost.key -out .ssl/localhost.crt
PS:沒有必要再做一次。
docker-compose.yml
檔案包含使用這些憑證的 nginx 反向代理程式。您可以透過 https://localhost 或 http://localhost 存取 Quepid。 (Quepid 仍可透過連接埠 80 上的 http 使用。)
在這裡新增開發文件!
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
來更新架構註解資料。
修改Gemfile
檔案然後運行:
bin/docker r bundle install
您將看到更新的Gemfile.lock
,並繼續將其和Gemfile
檢查到 Git 中。
我們使用 Angular 1 作為核心互動式應用程序,作為其中的一部分,我們對所有 UI 元件使用angular-ui-bootstrap
套件。該軟體包與 Bootstrap 版本 3 相關。
我們直接透過檔案bootstrap3.css
匯入 Bootstrap 3 CSS。
對於 Quepid 的其餘部分,我們使用 Bootstrap 5!這是使用 NPM 透過package.json
包含的。請參閱admin.js
中的行//= require bootstrap/dist/js/bootstrap.bundle
。
我們目前使用 Rails Sprockets 來編譯所有內容,但確實夢想轉向 Propshaft,也許還有 js-bundling。
aller字體來自FontSquirrel,.ttf轉換為.woff2格式。
執行./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+[type]@o19s.com
password: password
其中類型是以下之一:
admin
:管理員帳戶realisticActivity
:具有演示 Quepid 的各種案例的用戶,包括 Haystack Rating Party 演示案例和書籍,並且是“OSC”團隊的成員。100sOfQueries
:具有 100 個查詢的 Solr 案例的使用者(通常會停用)1000sOfQueries
:具有 1000 個查詢的 Solr 案例的使用者(通常會停用)oscOwner
:擁有團隊「OSC」的用戶oscMember
:屬於「OSC」團隊成員的用戶查看資料映射檔案以獲取有關應用程式資料結構的更多資訊。
透過bin/docker r bundle exec rake erd:image
重建 ERD
查看應用程式結構文件,以了解有關 Quepid 結構的更多資訊。
查看操作文檔文件,以了解如何為您的公司操作和配置 Quepid 的更多資訊。
如果沒有許多個人和組織的貢獻,Quepid 就不可能實現。
具體來說,我們要感謝 Erik Bugge 和 Kobler 的工作人員為 Quepid 6.4.0 中發布的「唯一評級」功能提供資助。
Quepid 並不總是開源的!查看該專案貢獻者清單的學分。
如果您想資助 Quepid 新功能的開發,請與我們聯絡!