Configuration¶

CLI Options¶

sapporo --help
usage: sapporo [-h] [--host str] [--port int] [--debug] [--run-dir PATH]
               [--service-info PATH] [--executable-workflows PATH]
               [--run-sh PATH] [--url-prefix str] [--base-url str]
               [--allow-origin str] [--auth-config PATH]
               [--run-remove-older-than-days int]
               [--snapshot-interval int]

options:
  -h, --help                       show this help message and exit
  --host str                       Host address for the service
                                   (default: 127.0.0.1)
  --port int                       Port number for the service
                                   (default: 1122)
  --debug                          Enable debug mode (default: False)
  --run-dir PATH                   Directory where the runs are stored
                                   (default: ./runs)
  --service-info PATH              Path to the service_info.json file
  --executable-workflows PATH      Path to the executable_workflows.json file
  --run-sh PATH                    Path to the run.sh script
  --url-prefix str                 URL prefix for the service endpoints
                                   (default: '', e.g., /sapporo/api)
  --base-url str                   Base URL for downloading the output files
                                   of the executed runs
                                   (default: http://{host}:{port}{url_prefix})
  --allow-origin str               Access-Control-Allow-Origin header value
                                   (default: *)
  --auth-config PATH               Path to the auth_config.json file
  --run-remove-older-than-days int Clean up run directories with a start time
                                   older than the specified number of days
                                   (must be >= 1)
  --snapshot-interval int          Interval in minutes for DB snapshot
                                   rebuilds and cleanup jobs (must be >= 1,
                                   default: 30)

Environment Variables¶

All CLI options can be set via environment variables with the SAPPORO_ prefix:

CLI Option	Environment Variable	Default
`--host`	`SAPPORO_HOST`	`127.0.0.1` (Docker 内では `0.0.0.0`)
`--port`	`SAPPORO_PORT`	`1122`
`--debug`	`SAPPORO_DEBUG`	`False`
`--run-dir`	`SAPPORO_RUN_DIR`	`./runs`
`--service-info`	`SAPPORO_SERVICE_INFO`	Built-in default
`--executable-workflows`	`SAPPORO_EXECUTABLE_WORKFLOWS`	Built-in default
`--run-sh`	`SAPPORO_RUN_SH`	Built-in default
`--url-prefix`	`SAPPORO_URL_PREFIX`	`""`
`--base-url`	`SAPPORO_BASE_URL`	`http://{host}:{port}{url_prefix}`
`--allow-origin`	`SAPPORO_ALLOW_ORIGIN`	`*`
`--auth-config`	`SAPPORO_AUTH_CONFIG`	Built-in default
`--run-remove-older-than-days`	`SAPPORO_RUN_REMOVE_OLDER_THAN_DAYS`	None
`--snapshot-interval`	`SAPPORO_SNAPSHOT_INTERVAL`	`30`
-	`SAPPORO_EXTRA_DOCKER_ARGS`	(unset)

SAPPORO_EXTRA_DOCKER_ARGS is used by run.sh to pass additional docker run flags to inner workflow engine containers. Use this to mount host directories that workflows need to read. Multiple flags can be space-separated. Applied to all engines.

# Example: mount a single directory
SAPPORO_EXTRA_DOCKER_ARGS="-v /data:/data"

# Example: mount multiple directories
SAPPORO_EXTRA_DOCKER_ARGS="-v /data:/data -v /ref:/ref"

Priority: CLI arguments > Environment variables > Default values.

service_info.json¶

Customize the response of GET /service-info by providing a JSON file via --service-info. The default is bundled at sapporo/service_info.json.

The file is partially merged with built-in defaults: fields present in the file override the defaults, while missing fields fall back to built-in values. This means you only need to specify the fields you want to customize.

executable_workflows.json¶

Restrict which workflows can be executed using --executable-workflows or SAPPORO_EXECUTABLE_WORKFLOWS.

Format:

{
  "workflows": [
    "https://example.com/workflow.cwl"
  ]
}

An empty array allows all workflows.
Each URL must be a remote resource (http/https).
Any workflow_url in POST /runs must match this list or the request returns a 400 Bad Request error.
Query available workflows via GET /executable-workflows.

Custom run.sh¶

Override the default run.sh script using --run-sh or SAPPORO_RUN_SH. This allows you to customize how workflow engines are invoked, add environment-specific upload or cleanup logic, or integrate new engines without modifying the bundled script. See Architecture - run.sh for details on the script structure.

Supported Engine / Workflow Type Combinations¶

The sapporo API validates engines and workflow types independently, but only certain combinations actually work at runtime. The default run.sh supports the following:

Engine	Workflow Type	Container Image	Notes
cwltool	CWL	`quay.io/commonwl/cwltool:3.1.20260108082145`
toil	CWL	`quay.io/ucsc_cgl/toil:9.1.1`
ep3	CWL	`ghcr.io/tom-tan/ep3:v1.7.0`
cromwell	WDL	`ghcr.io/sapporo-wes/cromwell-with-docker:92`	CWL support was removed in Cromwell 85
nextflow	NFL	`nextflow/nextflow:25.10.4`
snakemake	SMK	`snakemake/snakemake:v9.16.3`
streamflow	CWL	`alphaunito/streamflow:0.2.0.dev14`	Pre-release; uses cwl-runner interface

Output File Download¶

List output files: GET /runs/{run_id}/outputs
Download all outputs as zip: GET /runs/{run_id}/outputs?download=true
Download a specific file: GET /runs/{run_id}/outputs/{path}
Configure the base URL for downloads using --base-url or SAPPORO_BASE_URL. Files are accessible at {base_url}/runs/{run_id}/outputs/{path}.

Run Cleanup¶

Automatically remove old run directories using --run-remove-older-than-days or SAPPORO_RUN_REMOVE_OLDER_THAN_DAYS. The service periodically cleans up runs with a start time older than the specified number of days. The value must be an integer greater than or equal to 1; specifying 0 raises a ValueError.

Logging¶

Output¶

All log messages are written to stderr. Standard output is not used for logging.

Format¶

2025-01-01 12:00:00 INFO     sapporo.run - Starting workflow run

Format string: %(asctime)s %(levelprefix)s %(name)s - %(message)s

Log Level¶

Controlled by the --debug flag (or SAPPORO_DEBUG):

Flag	Root level	SQLAlchemy level
Off (default)	INFO	WARNING
`--debug`	DEBUG	INFO