Step-by-Step guide to setting up the NLDS client on JASMIN

Note

In January 2026, a more user friendly method of setting up the NLDS client on JASMIN rolled out to NLDS users. This now means that several steps that were previously in this document are no longer needed. This document has been shortened to reflect this. The improved workflow includes:

The access and secret keys required by the object store are now automatically generated by the nlds init command. The previous workflow of generating the object store access and secret keys is no longer required.
In addition, the nlds init command will now fill in all of the required values in the ~/.nlds-config file, including the user and group. This makes the setting up of the NLDS client much more user-friendly.
PyPi is now used for hosting the NLDS client, which makes installation much more straightforward for the user. pip install nlds-client can now be used, rather than the long GitHub URL as previously.
JASMIN users are automatically granted access to the nlds-cache-01-o object store tenancy on JASMIN. They no longer have to apply for access to this tenancy via the JASMIN accounts portal.

Prerequisites

This document assumes that the user has:

A JASMIN user account. This is covered extensively in the “Getting Started” section of the JASMIN help docs:
JASMIN : Docs : Getting Started.
Access to a Group Workspace. This is covered in the JASMIN docs:
JASMIN : Docs : What is a Group Workspace?
and
JASMIN : Docs : Apply for access to a GWS

This document will take you through the necessary steps to access NLDS as a JASMIN user:

Getting access to the NLDS object storage.
Installing the NLDS client.
Running the nlds init command.

Installing the NLDS client on a JASMIN scientific analysis server

First, please familiarise yourself with the JASMIN documentation on the scientific analysis servers: JASMIN : Docs : Scientific analysis servers.
We suggest that you use one of the sci-vm-0x servers to set up and use the NLDS client. An alternative is to use the JASMIN transfer servers (xfer-vm-0x), if it suits your workflow more. Details of these are here: JASMIN : Docs : Transfer servers.
Creating the virtual-evironment in your home directory will ensure that it is available from both the scientific analysis servers or the transfer servers.

Log into your chosen scientific analysis server:

> ssh <username>@sci-vm-01.jasmin.ac.uk

Follow the installation instructions here: NLDS : Docs : Installation. The steps are reproduced below:

> python3 -m venv ~/nlds-client
> source ~/nlds-client/bin/activate
> pip install --upgrade pip
> pip install nlds-client

Configuring the NLDS client

First make sure your are running the nlds-client virtual-environment that you created above. If you are not running it then issue the command:

> source ~/nlds-client/bin/activate

Run NLDS with the init command to create your NLDS config file. This file will be in your home directory with the name .nlds-config. The full path is ~/.nlds-config, also $HOME/.nlds-config. Use the -g|--group option to specify the default Group Workspace (GWS) when you are working with NLDS.

> nlds init -g <default gws>

This will produce the following text, and the password prompt at the end.

Initialising the Near-line Data Store...
• This application uses OAuth2 to authenticate with the server on your behalf.
• To do this it needs your password.  Your password is not stored.
• It is used to obtain an access token, which is stored in the file: ~/.nlds-token, and used for subsequent interactions with the server.
• It is also used to obtain object storage keys.  These are stored in the configuration file: ~/.nlds-config and used for interaction with the object storage cache.

Password:

Enter your JASMIN accounts password. The user name is automatically read in from your JASMIN login username. The following text will be output:

Successfully initialised, the config file at ~/.nlds-config has been updated with all of the necessary information to start using the NLDS.

You can now examine the config file with the following command:

> nano ~/.nlds-config

The file should look like the below example. Fields between < > characters should have values in them. If these fields contain the characters {{ }} then please delete the ~/.nlds-config file and try nlds init -g <gws> again. If this fails again then please contact the JASMIN helpdesk.

{
    "server": {
        "url": "https://nlds.jasmin.ac.uk",
        "api": "api/1.0.0"
    },
    "user": {
        "default_user": "< your JASMIN username >",
        "default_group": "< your default GWS >"
    },
    "authentication": {
        "oauth_client_id": "< redacted >",
        "oauth_client_secret": "< redacted >",
        "oauth_token_url": "< redacted >",
        "oauth_scopes": "< redacted >",
        "oauth_token_file_location": "~/.nlds-token"
    },
    "object_storage": {
        "tenancy": "nlds-cache-01.s3.jc.rl.ac.uk",
        "access_key": "< redacted >",
        "secret_key": "< redacted >"
    },
    "options": {
        "verify_certificates": true
    }
}

Running the NLDS client for the first time

You should now have a fully configured and functioning NLDS client. You can now run the NLDS client for the first time. Make sure the Python virtual-environment you created in NLDS : Docs : Installing the NLDS client is activated first, and then run nlds with the command stat.

> source ~/nlds-client/bin/activate
> nlds stat

The following text will be shown:

Usage: nlds stat [OPTIONS]
Try 'nlds stat --help' for help.

Error: Failed to get status of transaction(s) with user:<user>, group:<gws>
Reason: no transaction records found for user:< user > and group:< gws >

Because you issued the stat command with nlds, the status of all your NLDS requests will be shown. This is empty, as this is the first time you have run NLDS, and the error message reflects this by stating no transaction records found.

Next steps

Now that you have the NLDS client set up on JASMIN, you can go through the tutorial: NLDS : Docs : Tutorial.