Sapporo-web Document

Please refer to the GitHub - sapporo-wes/sapporo - docs/GettingStarted.md for instructions on how to use both Sapporo-service and Sapporo-web, which include simple examples.

We recommend using GitHub Pages - sapporo-wes/sapporo-web instead of deploying your own Sapporo-web, and to use it on the Google Chrome browser. All data in sapporo-web will be encrypted and stored in your browser's cookies.

Supplemental Usage Instructions (for Users)

Managing Workflow

After registering the workflow, Sapporo-web executes the run. If you are using Sapporo-service as a WES service, pre-registered workflows (which cannot be deleted) will be obtained.

Additionally, if Sapporo-service is running in a mode that only accepts pre-registered workflows, you will not be able to register workflows.

In the URL field, you can enter a remote URL or a local file name.

If a remote URL is entered, the URL will be treated as a workflow_url in POST /run.

If a local file name is entered, the file name will be treated as a workflow_url in POST /run, and the content will be attached as a WorkflowAttachment.

When you click "Submit," Sapporo-web will register the workflow.

Finally, please note that when you delete a workflow, Sapporo-web will delete all runs of that workflow. These runs will be removed from the information in Sapporo-web but not from Sapporo-service (WES service).

Workflow Execution

The documentation of the parameters for executing the workflow can be found in SawaggerHub - sapporo-wes-1.0.1-oas3.

In addition, samples of POST /run using curl are provided in GitHub - sapporo-wes/sapporo-service - tests/curl_example/post_runs.

When executing the workflow, it is important to name and select the appropriate Run Name and Workflow Engine according to your preference.

The Workflow Engine Parameters field are the options you want to pass to the workflow engine in key-value format.
Each key-value pair is concatenated with a space, as illustrated in the example below, which will be executed as some_kind_of_workflow_engine key value --debug -with-docker ubuntu:20.04.

To learn more about the detailed specification, please refer to GitHub - sapporo-wes/sapporo-service - sapporo/run.py - convert_wf_engine_params_str and GitHub - sapporo-wes/sapporo-service - sapporo/run.sh - run_cwltool.

The Tag field is free-form and can be filled with any information. Leaving it empty will result in a normal execution.

However, it can also be used for specific purposes, such as an S3 upload, as shown in GitHub - sapporo-wes/sapporo-service - sapporo/run.sh - s3-upload.

The Workflow Attachment section allows for the registration of the necessary files, such as tool.cwl and env.yml, as well as input files required to run the workflow.

To attach a file as a remote URL, use the text field above, which will download and place the file in the execution directory of Sapporo-service. To attach a file as a local file, use the file field below, which will be posted as binary data.

The file_name parameter is useful when creating a directory structure in the execution directory. If file_name is specified as some_dir/some_file, the file will be placed in some_dir/some_file after the mkdir command.

The handling of Workflow Parameters differs depending on the workflow engine. The example shown below is for CWL. Please refer to GitHub - sapporo-wes/sapporo-service - sapporo/run.sh to see how it is actually handled.

While JSON/YAML formats are accepted as input, if YAML is used, it will be converted to JSON before the POST request is made, based on the WES API specification. Additionally, it will be placed in the execution directory as workflow_params.json in the WES service.

Removal and Importation of Runs

If a run is deleted in Sapporo-web, it will not be deleted from Sapporo-service (WES service) because the WES API specification does not define the "delete" method. Therefore, a feature to import the deleted run or the run executed by others has been implemented.

The run_id is required for importation. It can be retrieved from the page of each run.

When the run_id is entered, Sapporo-web automatically retrieves information about the workflow and run.

Upon importing a run, Sapporo-web will automatically register the workflow associated with the run.

Developer Documentation

Deployment and Serving

Sapporo-web is developed in the static mode of Nuxt.js. Therefore, static HTML will be generated by running npm generate. Deploy this static HTML to a hosting service such as GitHub Pages.

# install dependencies
$ npm ci

# start developmet server
$ npm run dev

# build for production
$ npm run generate

You can also use the Nuxt.js feature to serve static HTML.

$ npm run start

Development Environment

Docker is used as the development environment.

$ docker compose -f docker-compose.dev.yml up -d

$ docker compose -f docker-compose.dev.yml exec app yarn dev

For more information, please check the following files:

• GitHub - sapporo-wes/sapporo-web - Dockerfile
• GitHub - sapporo-wes/sapporo-web - docker-compose.yml
• GitHub - sapporo-wes/sapporo-web - docker-compose.dev.yml

Environment Variables

Environment variables can be used to control the static HTML that is generated.

- SAPPORO_URL_PREFIX=/prefix/
- SAPPORO_LOAD_PRE_REGISTERED_serviceS=true # true or false

Using SAPPORO_URL_PREFIX is useful when deploying to a sub-directory of a URL. For example, when deploying to GitHub Pages, the following command is run in yarn deploy.

$ SAPPORO_URL_PREFIX=/sapporo-web/ yarn generate && push-dir --dir=dist --branch=gh-pages --cleanup

If SAPPORO_LOAD_PRE_REGISTERED_SERVICES is set to true, WES services can be registered in static HTML from the beginning. The WES service information that needs to be registered must be written in GitHub - sapporo-wes/sapporo-web - src/assets/preRegisteredservices.json.

If these environment variables are used, the static HTML needs to be regenerated each time the variables are changed by running nom generate.