# sapporo-web Japanese Document

使い方解説として、[GitHub - ddbj/sapporo - docs/GettingStarted.md](https://github.com/ddbj/sapporo/blob/master/docs/GettingStarted.md) を見てください。sapporo-service と sapporo-web の両方について、簡単な例とともに解説しています。

sapporo-web 本体は、GitHub Pages でデプロイされている [GitHub Pages - ddbj/sapporo-web](https://ddbj.github.io/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) からは削除されません。この点については [後述](https://hackmd.io/@suecharo/sapporo-web-docs-ja#Run-%E3%81%AE%E5%89%8A%E9%99%A4%E3%81%A8-import) します


### Workflow の実行

workflow の実行におけるパラメータのドキュメントとして [Swagger UI - sapporo-service - RunWorkflow](https://suecharo.github.io/sapporo-swagger-ui/dist/#/WorkflowExecutionService/RunWorkflow) が挙げられます。

また、curl を用いた `POST /run` のサンプルとして [GitHub - ddbj/sapporo-service - tests/curl_example/post_runs](https://github.com/ddbj/sapporo-service/tree/master/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](https://github.com/ddbj/sapporo-service/blob/c37698cd5413b3b3a0d2d3d9209fcdac39c196ee/sapporo/run.py#L118) や [GitHub - ddbj/sapporo-service - sapporo/run.sh - run_cwltool](https://github.com/ddbj/sapporo-service/blob/c37698cd5413b3b3a0d2d3d9209fcdac39c196ee/sapporo/run.sh#L35) を確認してください。

`Tags` は自由形式で何でも記述できます。通常の実行では空のままで大丈夫です。


Tags フィールドの活用の例としては、S3 Upload などが挙げられます。実際の実装として [GitHub - ddbj/sapporo-service - sapporo/run.sh - s3-upload](https://github.com/ddbj/sapporo-service/blob/c37698cd5413b3b3a0d2d3d9209fcdac39c196ee/sapporo/run.sh#L126) を確認してください。

`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](https://github.com/ddbj/sapporo-service/blob/master/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](https://nuxtjs.org) の 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](https://github.com/ddbj/sapporo-web/blob/master/Dockerfile)
- [GitHub - ddbj/sapporo-web - docker-compose.yml](https://github.com/ddbj/sapporo-web/blob/master/docker-compose.yml)
- [GitHub - ddbj/sapporo-web - docker-compose.dev.yml](https://github.com/ddbj/sapporo-web/blob/master/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](https://github.com/ddbj/sapporo-web/blob/master/src/assets/preRegisteredServices.json) に記述する必要があります。

これらの環境変数を使う場合は、変更するたびに `yarn generate` を実行して、静的 HTML を生成し直す必要があります。
# sapporo-web Japanese Document

使い方解説として、[GitHub - ddbj/sapporo - docs/GettingStarted.md](https://github.com/ddbj/sapporo/blob/master/docs/GettingStarted.md) を見てください。sapporo-service と sapporo-web の両方について、簡単な例とともに解説しています。

sapporo-web 本体は、GitHub Pages でデプロイされている [GitHub Pages - ddbj/sapporo-web](https://ddbj.github.io/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) からは削除されません。この点については [後述](https://hackmd.io/@suecharo/sapporo-web-docs-ja#Run-%E3%81%AE%E5%89%8A%E9%99%A4%E3%81%A8-import) します


### Workflow の実行

workflow の実行におけるパラメータのドキュメントとして [Swagger UI - sapporo-service - RunWorkflow](https://suecharo.github.io/sapporo-swagger-ui/dist/#/WorkflowExecutionService/RunWorkflow) が挙げられます。

また、curl を用いた `POST /run` のサンプルとして [GitHub - ddbj/sapporo-service - tests/curl_example/post_runs](https://github.com/ddbj/sapporo-service/tree/master/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](https://github.com/ddbj/sapporo-service/blob/c37698cd5413b3b3a0d2d3d9209fcdac39c196ee/sapporo/run.py#L118) や [GitHub - ddbj/sapporo-service - sapporo/run.sh - run_cwltool](https://github.com/ddbj/sapporo-service/blob/c37698cd5413b3b3a0d2d3d9209fcdac39c196ee/sapporo/run.sh#L35) を確認してください。

`Tags` は自由形式で何でも記述できます。通常の実行では空のままで大丈夫です。


Tags フィールドの活用の例としては、S3 Upload などが挙げられます。実際の実装として [GitHub - ddbj/sapporo-service - sapporo/run.sh - s3-upload](https://github.com/ddbj/sapporo-service/blob/c37698cd5413b3b3a0d2d3d9209fcdac39c196ee/sapporo/run.sh#L126) を確認してください。

`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](https://github.com/ddbj/sapporo-service/blob/master/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](https://nuxtjs.org) の 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](https://github.com/ddbj/sapporo-web/blob/master/Dockerfile)
- [GitHub - ddbj/sapporo-web - docker-compose.yml](https://github.com/ddbj/sapporo-web/blob/master/docker-compose.yml)
- [GitHub - ddbj/sapporo-web - docker-compose.dev.yml](https://github.com/ddbj/sapporo-web/blob/master/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](https://github.com/ddbj/sapporo-web/blob/master/src/assets/preRegisteredServices.json) に記述する必要があります。

これらの環境変数を使う場合は、変更するたびに `yarn generate` を実行して、静的 HTML を生成し直す必要があります。