Getting Started¶

This guide walks you through starting the sapporo-service, submitting a workflow, and retrieving the results.

Prerequisites¶

Docker (Docker Compose V2 included)
curl and jq for command-line interaction

Start the Service¶

Clone the repository and start the service with Docker Compose:

git clone https://github.com/sapporo-wes/sapporo-service.git
cd sapporo-service
docker compose up -d

Verify the Service¶

Confirm the service is running:

curl -fsSL localhost:1122/service-info | jq .

The response includes the service name, supported workflow engines, and API version.

Submit a Workflow¶

Submit a CWL workflow that runs quality control on paired-end FASTQ files using cwltool:

curl -fsSL -X POST \
  -F "workflow_type=CWL" \
  -F "workflow_url=https://raw.githubusercontent.com/sapporo-wes/sapporo-service/main/tests/resources/cwltool/trimming_and_qc_remote.cwl" \
  -F 'workflow_params={
    "fastq_1": {
      "class": "File",
      "location": "https://raw.githubusercontent.com/sapporo-wes/sapporo-service/main/tests/resources/cwltool/ERR034597_1.small.fq.gz"
    },
    "fastq_2": {
      "class": "File",
      "location": "https://raw.githubusercontent.com/sapporo-wes/sapporo-service/main/tests/resources/cwltool/ERR034597_2.small.fq.gz"
    }
  }' \
  -F "workflow_engine=cwltool" \
  localhost:1122/runs | jq .

The response contains a run_id:

{
  "run_id": "29109b85-7935-4e13-8773-9def402c7775"
}

Check Run Status¶

Poll the run status using the run_id from the previous step:

curl -fsSL localhost:1122/runs/${RUN_ID}/status | jq .

The run progresses through these states: QUEUED -> INITIALIZING -> RUNNING -> COMPLETE. See WES Compatibility for the full state list.

Retrieve the full run details:

curl -fsSL localhost:1122/runs/${RUN_ID} | jq .

Retrieve Outputs¶

Once the run reaches COMPLETE, list the output files:

curl -fsSL localhost:1122/runs/${RUN_ID}/outputs | jq .

Download all outputs as a zip archive:

curl -fsSL -o outputs.zip "localhost:1122/runs/${RUN_ID}/outputs?download=true"

Download a specific output file:

curl -fsSL -o result.html "localhost:1122/runs/${RUN_ID}/outputs/qc_result_1.html"

Next Steps¶

Installation - Install with pip, configure Docker volume mounts
Configuration - Customize CLI options, restrict executable workflows
Authentication - Enable JWT authentication
RO-Crate - Understand the provenance metadata generated for each run