REANA-Client is a component of the REANA reusable and reproducible research data analysis platform. It provides a command-line tool that allows researchers to submit, run, and manage their computational workflows.
- seed workspace with input code and data
- run computational workflows on remote compute clouds
- list submitted workflows and enquire about their statuses
- download results of finished workflows
$ # create new virtual environment
$ virtualenv ~/.virtualenvs/reana
$ source ~/.virtualenvs/reana/bin/activate
$ # install reana-client
$ pip install reana-clientThe detailed information on how to install and use REANA can be found in docs.reana.io.
The create and validate commands upload a scoped specification bundle for
server-side workflow loading. Declare every imported source explicitly under
workflow.files or workflow.directories so it is available to the loader.
For example, given this Snakemake project:
analysis/
├── reana.yaml
├── Snakefile
└── rules/
└── common.smk
where Snakefile contains include: "rules/common.smk", declare the included
source in reana.yaml:
version: 0.9.0
workflow:
type: snakemake
file: Snakefile
directories:
- rulesPaths are relative to the directory containing the selected specification.
Absolute paths, paths that escape through .., and symbolic links are rejected.
Use workflow.files only for workflow definitions and configuration needed
while loading the workflow; input datasets belong under inputs.files or
inputs.directories.
Validation snapshots accept at most 1,000 files, 2,000 directories, 100 MiB of file content, and 64 relative path components. Symbolic links are not followed.
reana-client validate --environments performs offline image-reference checks
and reports effective runtime identities. Add --pull to verify availability
and inspect those images with your local container runtime and registry
credentials; the REANA server does not contact image registries.
reana-client authenticates against your REANA server's OIDC issuer, not with a
static long-lived token: run reana-client login once (add --headless on a
machine with no browser, e.g. over SSH, to use the device flow instead of
opening a local browser) and the resulting credentials are stored,
permission-restricted (0600), at ~/.config/reana/reana-client.json by
default, or at the path in the REANA_CLIENT_CONFIG environment variable if
set. reana-client logout revokes and clears them.
Both login flows need a one-time interactive step (a browser, or opening a device-flow URL), so there is currently no fully unattended, credential-free way to authenticate a CI job or cron script from scratch. The supported pattern for CI/automation is to reuse credentials obtained once interactively:
-
On a machine with a browser (or
--headlessover SSH), run:$ REANA_CLIENT_CONFIG=./reana-client.json reana-client login --server-url <your-server> -
Store the resulting
reana-client.jsonfile's contents as a CI secret (e.g. a masked/protected variable), not in the repository. -
In the CI job, write that secret out to a private, uniquely-named file and point
REANA_CLIENT_CONFIGat it before runningreana-client. Plain shell redirection (echo ... > /tmp/reana-client.json) creates the file world-readable by default (mode0666minus umask) at a predictable path, exposing the refresh token to other users on a shared runner untilreana-clientitself happens to rewrite it; create it locked down from the start instead, and clean it up afterwards:$ credential_file="$(mktemp)" $ trap 'rm -f "$credential_file"' EXIT $ chmod 600 "$credential_file" $ printf '%s' "$REANA_CREDENTIALS_SECRET" > "$credential_file" $ export REANA_CLIENT_CONFIG="$credential_file" $ reana-client ping
The stored refresh token has the lifetime your identity provider issues it with;
a long-running or infrequently-triggered CI pipeline can outlive it and will
need the credential file refreshed with a new interactive login (repeat step 1)
— there is no automatic renewal beyond that token's own lifetime. Older REANA
releases accepted a static, non-expiring REANA_ACCESS_TOKEN; that pattern is
no longer accepted by servers running OIDC/JWT authentication, and
reana-client will report a clear error if it detects one instead of a JWT.
This pattern assumes your identity provider does not rotate refresh tokens for
this client (or does not reject reuse of the last-issued one). reana-client
correctly persists a replacement refresh token returned by the issuer, but only
into that job's own local copy of the credential file — the CI secret itself is
never updated. If your issuer rotates refresh tokens and rejects reuse (a
supported Keycloak setting, among others), the first job to refresh invalidates
the token for every subsequent job restoring the now-stale CI secret, which will
then fail with invalid_grant; concurrent jobs can fail the same way, since
each starts from its own copy. If your issuer does rotate refresh tokens, either
configure a non-rotating refresh token for this CI service account if your
provider supports it, or write the credential file back to a mutable, serialized
secret store after each job instead of relying on an immutable CI secret.
