このドキュメントでは、Yevis workflow registry の構築と維持について説明します。
ワークフローのメタデータと GA4GH Tool Registry Service (TRS) API を配布するための GitHub Repository を準備します。
テンプレートとして、GitHub - sapporo-wes/yevis-workflow-registry-template を使用します。
この Link をクリックすると、GitHub Repository の作成が開始されます。
Include all branched
オプションにチェック入れることを忘れずに。
README.md
と LICENSE
はファイルは自由に設定できます。
作成したリポジトリの [Settings] - [Pages]
において、GitHub Pages を設定します。
また、[Settings] - [Actions] - [General]
において、ワークフローのパーミッションが Read
と Write
のアクセス権を持っていることを確認します。
この Link から Zenodo Token を生成します。
必要なスコープは以下の通りです。
deposit:actions
deposit:write
次に、作成したリポジトリの [Settings] - [Secrets] - [Actions]
において、生成されたトークンを GitHub Secrets として ZENODO_TOKEN
という名前で登録します。
yevis-web
の用意ワークフローをブラウズするための Web Application、sapporo-wes/yevis-web
をデプロイします。
この Link をクリックすると、GitHub Repository の作成が開始されます。
README.md
と LICENSE
はファイルは自由に設定できます。
[Settings] - [Actions] - [General]
において、ワークフローのパーミッションが Read
と Write
のアクセス権を持っていることを確認します。
次に、作成したリポジトリの [Actions] - [deploy-web]
にある GitHub Actions ワークフローを実行します。
ワークフローを実行するために、以下のパラメータを入力します。
Yevis workflow registry
: Section 1.1.
で作成した workflow registry の GitHub リポジトリ名 (e.g., suecharo/yevis-getting-started
)GitHub Pages branch
: GitHub Pages の branch 名TRS API endpoint
: TRS API の URL (e.g., https://suecharo.github.io/yevis-getting-started/
)deploy-dispatch
ワークフローが完了したら、[Settings] - [Pages]
に移動して GitHub Pages を設定します。
GitHub Pages の deploy アクションが完了すると、yevis-web
が GitHub Pages にデプロイされます。
ワークフローの登録は、3 つのプロセスに分かれています。
yevis-cli
をインストールします。
yevis-cli
- Installation を参照してください。
このドキュメントでは、M1 Mac を使用しているため、Docker 環境を使用します (binary は Linux 用にのみビルドされています)。
$ curl -fsSL -O https://raw.githubusercontent.com/sapporo-wes/yevis-cli/main/compose.yml
$ docker compose up -d
[+] Running 2/2
⠿ Network yevis-network Created 0.0s
⠿ Container yevis-cli Started 0.2s
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
929d689b61f2 ghcr.io/sapporo-wes/yevis-cli:0.4.0 "sleep infinity" 34 seconds ago Up 33 seconds yevis-cli
$ docker compose exec app bash
root@929d689b61f2:/app# yevis --help
yevis 0.4.0
DDBJ(Bioinformatics and DDBJ Center)
...
次に yevis-cli
内で使用する GitHub Personal Access Token
を取得します。
GitHub Personal Access Token
の生成方法については、 GitHub Docs - Creating a personal access token を参照してください。
必要なスコープは以下の通りです。
repo - public_repo
user - read:user
生成された、GitHub Personal Access Token
は、以下のいずれかの方法で yevis-cli
に渡します。
.env
file: .env
ファイルに GITHUB_TOKEN=<PASTE_YOUR_TOKEN>
と記述するGITHUB_TOKEN
を設定する--gh-token <PASTE_YOUR_TOKEN>
を使用する今回は、環境変数を使用します。
export GITHUB_TOKEN=<PASTE_YOUR_TOKEN>
ワークフローのメタデータをまとめたファイル yevis-metadata.yml
を作成します。
ワークフローの例として、https://github.com/pitagora-network/pitagora-cwl/blob/master/workflows/download-fastq/download-fastq.cwl
を使用します。
注意すべき点として:
target
field を使って、tools/tool.cwl
のように相対パスでファイルを配置することができます。https://<zenodo_base>/tools_tool.cwl
のような flatten された URL としてファイルが hosting されますrun: tools/tool.cwl
のような行が wf.cwl
が含まれるとエラーになります
cwltool --pack
を実行して、一つのファイルにまとめてください以下のように、yevis make-template
を使用して yevis-metadata.yml
のテンプレートファイルを作成します。
$ yevis make-template https://github.com/pitagora-network/pitagora-cwl/blob/master/tools/download-sra/download-sra.cwl
Start yevis
Running make-template
Making a template from https://github.com/pitagora-network/pitagora-cwl/blob/master/tools/download-sra/download-sra.cwl
Success make-template
$ ls yevis-metadata.yml
yevis-metadata.yml
生成された yevis-metadata.yml
を以下のように編集します。
id: be733bb3-9d9c-41af-a6e2-292751351b1e
version: 1.0.0
license: Apache-2.0
authors:
- github_account: suecharo
name: Due, John
affiliation: "The University of Tokyo"
orcid: "0000-0003-2765-0049"
workflow:
name: Yevis getting started - Download SRA
readme: "https://github.com/pitagora-network/pitagora-cwl/blob/master/README.md"
language:
type: CWL
version: v1.0
files:
- url: "https://github.com/pitagora-network/pitagora-cwl/blob/master/tools/download-sra/download-sra.cwl"
target: download-sra.cwl
type: primary
testing:
- id: test_1
files:
- url: "https://github.com/pitagora-network/pitagora-cwl/blob/master/tools/download-sra/download-sra.yml"
target: wf_params.yml
type: wf_params
yevis-metadata.yml
を yevis validate
でバリデートします。
$ yevis validate ./yevis-metadata.yml
Start yevis
Running validate
Validating ./yevis-metadata.yml
Success validate
テストを実行するには、yevis test
を使用します。
--wes-location
を指定しない場合、yevis-cli
が Docker を使用して Sapporo を起動し、テストを実行します。
そのため、docker
command と Docker Socket が利用可能である必要があります。
$ yevis test ./yevis-metadata.yml
Start yevis
Running validate
Validating ./yevis-metadata.yml
Success validate
Running test
Starting sapporo-service using docker_host: unix:///var/run/docker.sock
Stdout from docker:
51841ce5da7ff0e166cd9ad2dfb564d6a0ef626fbac72fb43a96c118df43811d
Use WES location: http://yevis-sapporo-service:1122/ for testing
Test workflow_id: be733bb3-9d9c-41af-a6e2-292751351b1e, version: 1.0.0
Testing test case: test_1
WES run_id: a45f20ba-6b76-40b2-ac12-f669a2b82ce2
Complete test case: test_1
Passed all test cases in workflow_id: be733bb3-9d9c-41af-a6e2-292751351b1e, version: 1.0.0
Stopping sapporo-service
Stdout from docker:
yevis-sapporo-service
Success test
Host OS 上では、以下のコンテナが起動しています。
$ docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
ff447ea21f90 ghcr.io/inutano/download-sra:177141a "download-sra -r ddb…" 3 seconds ago Up 3 seconds focused_rhodes
bc58bac48e3c quay.io/commonwl/cwltool:3.1.20211107152837 "/cwltool-in-docker.…" 49 seconds ago Up 48 seconds sweet_saha
51841ce5da7f ghcr.io/sapporo-wes/sapporo-service:1.1.2 "tini -- sapporo --r…" 56 seconds ago Up 56 seconds 1122/tcp yevis-sapporo-service
33d426de77c7 yevis-cli:0.4.0 "sleep infinity" 3 hours ago Up 2 minutes yevis-cli
Section 1.
で作成したリポジトリに対する Pull Request を作成します。
Validation と Test を pass しない限り、Pull Request を作成できません。
$ yevis pull-request -r suecharo/yevis-getting-started ./yevis-metadata.yml
Start yevis
Running validate
Validating ./yevis-metadata.yml
Success validate
Running test
Starting sapporo-service using docker_host: unix:///var/run/docker.sock
Stdout from docker:
8c693de066c12f64e5f322a9e0ecc555b509d1e4db8e072335cfa16083836516
Use WES location: http://yevis-sapporo-service:1122/ for testing
Test workflow_id: be733bb3-9d9c-41af-a6e2-292751351b1e, version: 1.0.0
Testing test case: test_1
WES run_id: 057e23f9-8527-49e2-9e50-f18989ab6a82
Complete test case: test_1
Passed all test cases in workflow_id: be733bb3-9d9c-41af-a6e2-292751351b1e, version: 1.0.0
Stopping sapporo-service
Stdout from docker:
yevis-sapporo-service
Success test
Running pull-request
Creating a pull request based on workflow_id: be733bb3-9d9c-41af-a6e2-292751351b1e, version: 1.0.0
Creating branch be733bb3-9d9c-41af-a6e2-292751351b1e
Branch be733bb3-9d9c-41af-a6e2-292751351b1e has been created
Creating pull request to suecharo/yevis-getting-started
Pull Request URL: https://github.com/suecharo/yevis-getting-started/pull/1
Success pull-request
Pull Request として submit されたワークフローは、GitHub Action - yevis-test-pr.yml
によって自動的に Validation and Test されます。
その後、Pull Request をマージします。
Pull Request をマージした後、GitHub Action - yevis-publish-pr.yml
によって自動的に publication されます。
Publication workflow が実行中:
Publication workflow が終了:
次に、Section 2.
で deploy した yevis-web
を見ると、公開したワークフローをブラウズできます。
yevis-web
:
Zenodo: