2. Getting Started

2.1. Install REANA client

If you are a researcher that is interested in running analyses on the REANA cloud, all you need to install is the reana-client, ideally in a new virtual environment:

$ # create new virtual environment
$ virtualenv ~/.virtualenvs/myreana
$ source ~/.virtualenvs/myreana/bin/activate
$ # install reana-client
$ pip install reana-client

2.2. Select REANA cloud

You can now select the REANA cloud instance where to run your analyses by setting the REANA_SERVER_URL variable appropriately. You also have to provide a valid access token through the environment variable REANA_ACCESS_TOKEN. For example:

$ export REANA_SERVER_URL=https://reana.cern.ch
$ export REANA_ACCESS_TOKEN=XXXXXXX

The access token should have been given to you by the administrators of the REANA cloud instance you are using.

Hint for developers

Note that if you are running REANA cluster locally on your laptop – i.e. you are yourself the administrator of your REANA cloud instance – then you can use:

$ eval $(reana-cluster env --include-admin-token)

which will set both environment variables for you. Please see the REANA-Cluster’s Getting Started guide for more information.

2.3. Run example analysis

Let us take reana-demo-helloworld as a simple example analysis to run on our REANA cloud.

Please familiarise yourself with the structure of reana-demo-helloworld GitHub repository and how it specifies the analysis code, data, environment, and the computation workflow to produce the analysis output. The reana-client usage scenario will be identical in submitting any complex research data computational workflows.

Let us start by testing connection to the REANA cloud:

$ reana-client ping
Server is running.

We can now create a new computational workflow:

$ reana-client create
workflow.1

This created a workflow with the default name “workflow” and run number “1”.

Note that if you would like to give your workflow a different name, you can use the -n argument:

$ reana-client create -n myfirstdemo
myfirstdemo.1

We can check the status of our previously created workflow:

$ reana-client status -w workflow.1
NAME       RUN_NUMBER   CREATED               STATUS    PROGRESS
workflow   1            2018-08-10T07:27:15   created   -/-

Note that instead of passing -w argument with the workflow name every time, we can define a new environment variable REANA_WORKON which specifies the workflow we would like to work on:

$ export REANA_WORKON=workflow.1

Let us upload our code:

$ reana-client upload ./code/helloworld.py
File code/helloworld.py was successfully uploaded.

and check whether it indeed appears seeded in our workspace:

$ reana-client list
NAME                 SIZE   LAST-MODIFIED
code/helloworld.py   2905   2018-08-10T07:29:54

Similarly, let us now upload the input data file:

$ reana-client upload ./data/names.txt
File data/names.txt was successfully uploaded.

and check whether it was well seeded into our input workspace:

$ reana-client list
NAME                 SIZE   LAST-MODIFIED
data/names.txt         18   2018-08-10T07:31:15
code/helloworld.py   2905   2018-08-10T07:29:54

Now that the input data and code was uploaded, we can start the workflow execution:

$ reana-client start
workflow.1 has been started.

Let us enquire about its running status; we may see that it is still in the “running” state:

$ reana-client status
NAME       RUN_NUMBER   CREATED               STATUS    PROGRESS
workflow   1            2018-08-10T07:27:15   running   0/1

After a few minutes, the workflow should be finished:

$ reana-client status
NAME       RUN_NUMBER   CREATED               STATUS     PROGRESS
workflow   1            2018-08-10T07:27:15   finished   1/1

We can now check the list of output files:

$ reana-client list
NAME                    SIZE   LAST-MODIFIED
code/helloworld.py      2905   2018-08-06T13:58:21
data/names.txt            18   2018-08-06T13:59:59
results/greetings.txt     32   2018-08-06T14:01:02

and retrieve the resulting output file:

$ reana-client download results/greetings.txt
File results/greetings.txt downloaded to /home/reana/reanahub/reana-demo-helloworld.

Let us see whether we got the expected output:

$ cat helloworld/greetings.txt
Hello Jane Doe!
Hello John Doe!

2.4. Next steps

For more information, please see:

  • Looking for a more comprehensive REANA client user manual? See User guide
  • Looking for tips how to develop REANA client component? See Developer guide
  • Looking for REANA client command-line API reference? See CLI API