HackMD
sapporo-web Japanese Document
使い方解説として、GitHub - ddbj/sapporo - docs/GettingStarted.md を見てください。sapporo-service と sapporo-web の両方について、簡単な例とともに解説しています。
sapporo-web 本体は、GitHub Pages でデプロイされている GitHub Pages - ddbj/sapporo-web を使うことをおすすめします (Google Chrome browser で動作検証をしました)。sapporo-web 内で使用する全てのデータは、ユーザーのブラウザーの Cookie に暗号化されて保存されます。
使い方解説の補足 (ユーザ向け)
Workflow の管理
sapporo-web は workflow を登録してから実行します。sapporo-service を WES service として使っている場合は、service に事前に登録された workflow が取得されます (これらの管理者により登録された workflow は削除できません)。
また、sapporo-service が事前登録された workflow のみを受け付けるモードで動作している場合は、別のワークフローを登録 (Register) できません。
URL のフィールドには、remote URL かパソコン内のローカルファイルのパス (local file name) を入力することができます。
remote URL が入力されているときは、その URL が POST /run の workflow_url として扱われます。
local file name が入力されているときは、その file name が POST /run の workflow_url として扱われ、Content が WorkflowAttachment として attach されます。
SUBMIT を押すと、workflow が登録されます。
最後に、workflow を削除すると、その workflow から実行された run は全て削除されるので気をつけてください。sapporo-web の情報から削除されるだけで、ワークフローが実行された sapporo-service (WES service) からは削除されません。この点については 後述 します
Workflow の実行
workflow の実行におけるパラメータのドキュメントとして Swagger UI - sapporo-service - RunWorkflow が挙げられます。
また、curl を用いた POST /run のサンプルとして GitHub - ddbj/sapporo-service - tests/curl_example/post_runs が用意されています。
Run Name と Workflow Engine はそれぞれの好みで命名・選択してください。
Workflow Engine Parameters は workflow engine に渡したい Option を key-value 形式でで記述します。下の例だと some_kind_of_workflow_engine key value --debug -with-docker ubuntu:20.04 のように実行されます。すべての key value がそれぞれ空白で結合された形で workflow engine に渡されます。
詳しい仕様を知りたい場合は、GitHub - ddbj/sapporo-service - sapporo/run.py - generate_wf_engine_params_str や GitHub - ddbj/sapporo-service - sapporo/run.sh - run_cwltool を確認してください。
Tags は自由形式で何でも記述できます。通常の実行では空のままで大丈夫です。
Tags フィールドの活用の例としては、S3 Upload などが挙げられます。実際の実装として GitHub - ddbj/sapporo-service - sapporo/run.sh - s3-upload を確認してください。
Workflow Attachment は workflow 実行に必要なファイル (e.g. tool.cwl や env.yml) や入力ファイルを登録します。
file を Remote URL として attach したい場合は、上のテキストフィールドを使ってください (sapporo-service 内で download され実行 directory に配置されます)。file を local file として attach したい場合は、下のファイルフィールドを使ってください (binary data として POST されます)。
file_name は実行 directory に directory 構造をもたせたいときに便利です。file_name: some_dir/some_file として指定した場合、<exe_dir>/some_dir/some_file として、mkdir した後に file が配置されます。
Workflow Parameters は workflow engine よって扱いが異なります (下は CWL の例です)。実際にどのように扱われるかは GitHub - ddbj/sapporo-service - sapporo/run.sh を確認してください。
JSON/YAML 形式を入力として受け付けていますが、YAML 形式が入力された場合、JSON 形式に変換してから POST します (WES API の仕様に基づく)。また、WES service 内においては workflow_params.json として実行 directory に配置されます。
Run の削除と import
sapporo-web 内で run を削除しても sapporo-service (WES service) から run は削除されません (WES API の仕様において delete が定義されていないため)。そのため、delete した run や他の人が実行した run を import する機能が実装されています。
import には run_id が必要です。
run_id はそれぞれの run の page から取得することができます。
run_id を入力すると、自動的に workflow や run に関する情報が取得されます。sapporo-web の Data 構造として run は workflow に紐付かなければならないため、run を import する際、その run に紐付く workflow が自動的に register されます。
Data の管理
画面右上の state button を押すと、Cookie に保存されている Data を確認できるページに移動します。
このページでは、Data を dump したり、削除することができます。
Force Clear State Button を使うと、通常の画面では消すことができない事前登録された Service や Workflow を強制的に削除することができます。
開発者のためのドキュメント
Deploy and Serve
sapporo-web は Nuxt.js の static mode で開発されています。そのため、yarn generate で静的 HTML が生成されます。この静的 HTML を GitHub Pages のような Hosting Server に Deploy してください。ご自分で用意した Web サーバに配置することも可能です。
# install dependencies
$ yarn install
# build for production
$ yarn generate
また、Nuxt.js の機能を使って、静的 HTML を Serve することもできます。
$ yarn start
開発環境
Docker を開発環境として使っています。
$ docker-compose -f docker-compose.dev.yml up -d
$ docker-compose -f docker-compose.dev.yml exec app yarn dev
詳しくは、下のファイルを確認してください。
- GitHub - ddbj/sapporo-web - Dockerfile
- GitHub - ddbj/sapporo-web - docker-compose.yml
- GitHub - ddbj/sapporo-web - docker-compose.dev.yml
環境変数
環境変数を使って生成される、静的 HTML を制御することができます。
- SAPPORO_URL_PREFIX=/prefix/
- SAPPORO_LOAD_PRE_REGISTERED_SERVICES=true # true or false
SAPPORO_URL_PREFIX を使うと、URL の sub-directory に deploy するとき便利です。例えば yarn deploy の中では、
$ SAPPORO_URL_PREFIX=/sapporo-web/ yarn generate && push-dir --dir=dist --branch=gh-pages --cleanup
のようにして、GitHub Pages に deploy しています。
SAPPORO_LOAD_PRE_REGISTERED_SERVICES を使うと、静的 HTML に最初から WES service を登録しておくことができます。登録しておきたい WES service の情報は GitHub - ddbj/sapporo-web - src/assets/preRegisteredServices.json に記述する必要があります。
これらの環境変数を使う場合は、変更するたびに yarn generate を実行して、静的 HTML を生成し直す必要があります。
sapporo-web Japanese Document
使い方解説として、GitHub - ddbj/sapporo - docs/GettingStarted.md を見てください。sapporo-service と sapporo-web の両方について、簡単な例とともに解説しています。
sapporo-web 本体は、GitHub Pages でデプロイされている GitHub Pages - ddbj/sapporo-web を使うことをおすすめします (Google Chrome browser で動作検証をしました)。sapporo-web 内で使用する全てのデータは、ユーザーのブラウザーの Cookie に暗号化されて保存されます。
使い方解説の補足 (ユーザ向け)
Workflow の管理
sapporo-web は workflow を登録してから実行します。sapporo-service を WES service として使っている場合は、service に事前に登録された workflow が取得されます (これらの管理者により登録された workflow は削除できません)。
また、sapporo-service が事前登録された workflow のみを受け付けるモードで動作している場合は、別のワークフローを登録 (Register) できません。
URL のフィールドには、remote URL かパソコン内のローカルファイルのパス (local file name) を入力することができます。
remote URL が入力されているときは、その URL が POST /run の workflow_url として扱われます。
local file name が入力されているときは、その file name が POST /run の workflow_url として扱われ、Content が WorkflowAttachment として attach されます。
SUBMIT を押すと、workflow が登録されます。
最後に、workflow を削除すると、その workflow から実行された run は全て削除されるので気をつけてください。sapporo-web の情報から削除されるだけで、ワークフローが実行された sapporo-service (WES service) からは削除されません。この点については 後述 します
Workflow の実行
workflow の実行におけるパラメータのドキュメントとして Swagger UI - sapporo-service - RunWorkflow が挙げられます。
また、curl を用いた POST /run のサンプルとして GitHub - ddbj/sapporo-service - tests/curl_example/post_runs が用意されています。
Run Name と Workflow Engine はそれぞれの好みで命名・選択してください。
Workflow Engine Parameters は workflow engine に渡したい Option を key-value 形式でで記述します。下の例だと some_kind_of_workflow_engine key value --debug -with-docker ubuntu:20.04 のように実行されます。すべての key value がそれぞれ空白で結合された形で workflow engine に渡されます。
詳しい仕様を知りたい場合は、GitHub - ddbj/sapporo-service - sapporo/run.py - generate_wf_engine_params_str や GitHub - ddbj/sapporo-service - sapporo/run.sh - run_cwltool を確認してください。
Tags は自由形式で何でも記述できます。通常の実行では空のままで大丈夫です。
Tags フィールドの活用の例としては、S3 Upload などが挙げられます。実際の実装として GitHub - ddbj/sapporo-service - sapporo/run.sh - s3-upload を確認してください。
Workflow Attachment は workflow 実行に必要なファイル (e.g. tool.cwl や env.yml) や入力ファイルを登録します。
file を Remote URL として attach したい場合は、上のテキストフィールドを使ってください (sapporo-service 内で download され実行 directory に配置されます)。file を local file として attach したい場合は、下のファイルフィールドを使ってください (binary data として POST されます)。
file_name は実行 directory に directory 構造をもたせたいときに便利です。file_name: some_dir/some_file として指定した場合、<exe_dir>/some_dir/some_file として、mkdir した後に file が配置されます。
Workflow Parameters は workflow engine よって扱いが異なります (下は CWL の例です)。実際にどのように扱われるかは GitHub - ddbj/sapporo-service - sapporo/run.sh を確認してください。
JSON/YAML 形式を入力として受け付けていますが、YAML 形式が入力された場合、JSON 形式に変換してから POST します (WES API の仕様に基づく)。また、WES service 内においては workflow_params.json として実行 directory に配置されます。
Run の削除と import
sapporo-web 内で run を削除しても sapporo-service (WES service) から run は削除されません (WES API の仕様において delete が定義されていないため)。そのため、delete した run や他の人が実行した run を import する機能が実装されています。
import には run_id が必要です。
run_id はそれぞれの run の page から取得することができます。
run_id を入力すると、自動的に workflow や run に関する情報が取得されます。sapporo-web の Data 構造として run は workflow に紐付かなければならないため、run を import する際、その run に紐付く workflow が自動的に register されます。
Data の管理
画面右上の state button を押すと、Cookie に保存されている Data を確認できるページに移動します。
このページでは、Data を dump したり、削除することができます。
Force Clear State Button を使うと、通常の画面では消すことができない事前登録された Service や Workflow を強制的に削除することができます。
開発者のためのドキュメント
Deploy and Serve
sapporo-web は Nuxt.js の static mode で開発されています。そのため、yarn generate で静的 HTML が生成されます。この静的 HTML を GitHub Pages のような Hosting Server に Deploy してください。ご自分で用意した Web サーバに配置することも可能です。
# install dependencies
$ yarn install
# build for production
$ yarn generate
また、Nuxt.js の機能を使って、静的 HTML を Serve することもできます。
$ yarn start
開発環境
Docker を開発環境として使っています。
$ docker-compose -f docker-compose.dev.yml up -d
$ docker-compose -f docker-compose.dev.yml exec app yarn dev
詳しくは、下のファイルを確認してください。
- GitHub - ddbj/sapporo-web - Dockerfile
- GitHub - ddbj/sapporo-web - docker-compose.yml
- GitHub - ddbj/sapporo-web - docker-compose.dev.yml
環境変数
環境変数を使って生成される、静的 HTML を制御することができます。
- SAPPORO_URL_PREFIX=/prefix/
- SAPPORO_LOAD_PRE_REGISTERED_SERVICES=true # true or false
SAPPORO_URL_PREFIX を使うと、URL の sub-directory に deploy するとき便利です。例えば yarn deploy の中では、
$ SAPPORO_URL_PREFIX=/sapporo-web/ yarn generate && push-dir --dir=dist --branch=gh-pages --cleanup
のようにして、GitHub Pages に deploy しています。
SAPPORO_LOAD_PRE_REGISTERED_SERVICES を使うと、静的 HTML に最初から WES service を登録しておくことができます。登録しておきたい WES service の情報は GitHub - ddbj/sapporo-web - src/assets/preRegisteredServices.json に記述する必要があります。
これらの環境変数を使う場合は、変更するたびに yarn generate を実行して、静的 HTML を生成し直す必要があります。
