# Sapporo-web Document
Please refer to the [GitHub - sapporo-wes/sapporo - docs/GettingStarted.md](https://github.com/sapporo-wes/sapporo/blob/main/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](https://sapporo-wes.github.io/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](https://app.swaggerhub.com/apis/suecharo/sapporo-wes/sapporo-wes-1.0.1-oas3#/default/RunWorkflow).
In addition, samples of `POST /run` using `curl` are provided in [GitHub - sapporo-wes/sapporo-service - tests/curl_example/post_runs](https://github.com/sapporo-wes/sapporo-service/tree/main/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](https://github.com/sapporo-wes/sapporo-service/blob/15e913e279fc8652e16ad0fd3b5c2e6529acbc96/sapporo/run.py#L187) and [GitHub - sapporo-wes/sapporo-service - sapporo/run.sh - run_cwltool](https://github.com/sapporo-wes/sapporo-service/blob/c37698cd5413b3b3a0d2d3d9209fcdac39c196ee/sapporo/run.sh#L35).
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](https://github.com/sapporo-wes/sapporo-service/blob/15e913e279fc8652e16ad0fd3b5c2e6529acbc96/sapporo/run.sh#L162).
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](https://github.com/sapporo-wes/sapporo-service/blob/main/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](https://nuxtjs.org). Therefore, static HTML will be generated by running `npm generate`. Deploy this static HTML to a hosting service such as GitHub Pages.
```shell
# 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.
```shell
$ npm run start
```
### Development Environment
Docker is used as the development environment.
```shell
$ 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](https://github.com/sapporo-wes/sapporo-web/blob/main/Dockerfile)
- [GitHub - sapporo-wes/sapporo-web - docker-compose.yml](https://github.com/sapporo-wes/sapporo-web/blob/main/docker-compose.yml)
- [GitHub - sapporo-wes/sapporo-web - docker-compose.dev.yml](https://github.com/sapporo-wes/sapporo-web/blob/main/docker-compose.dev.yml)
### Environment Variables
Environment variables can be used to control the static HTML that is generated.
```yaml
- 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`.
```shell
$ 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](https://github.com/sapporo-wes/sapporo-web/blob/main/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`.
Sign in with Wallet
Connect another wallet