Configuring the JAWS Client: A Step-by-Step Guide

Summary

If your data is stored on the NERSC file system, you must have a NERSC account and be a member of the “genome” group (or ‘nmdc’ for the NMDC project). Likewise, if your data is located on Dori, you will log into Dori to run jobs. If you have questions about how to get an account, please get in touch with our team.

These are the steps you’ll be required to complete to start running a pipeline in JAWS:

  1. get JAWS token;

  2. create a configuration file to store your token;

  3. choose how you’d like to access the JAWS Client:

    • Option 1: activate the JAWS virtual environment using module load jaws;

    • Option 2: use jaws client container;

    • Option 3: install jaws-client into your virtual environment,

JAWS TOKEN

JAWS TOKEN

Before completing the JAWS setup below, you need to get a JAWS token from the JAWS admin.

Please fill this out form. The JAWS Team will contact you soon!

Setting up JAWS Client

1. Create a config file that has the JAWS token in it:

Choose the site where your data will reside and thus where you will be submitting to JAWS.

  • Log in to DORI

cp /clusterfs/jgi/groups/dsi/homes/svc-jaws/dori-prod/jaws.conf ~/jaws.conf
chmod 600 ~/jaws.conf

  • Log in to NERSC - Perlmutter

cp /global/cfs/cdirs/jaws/perlmutter-prod/jaws.conf ~/jaws.conf
chmod 600 ~/jaws.conf

  • Log in to NERSC - NMDC

cp /global/common/software/m3408/nmdc-prod/jaws.conf ~/jaws.conf
chmod 600 ~/jaws.conf

  • Log in to TAHOMA - NMDC

cp /tahoma/mscnmdc/jaws-install/jaws-client/nmdc_tahoma-prod/jaws.conf ~/jaws.conf
chmod 600 ~/jaws.conf

2. Add your token and default_team to ~/jaws.conf:

[USER]
token = <your token>
default_team = <team ID>

Find here information about JAWS Teams.

Use JAWS CLI

To use the JAWS CLI, you can choose from three options tailored to different needs and setups.

  1. You could activate the JAWS environment with the command module load jaws for easy integration.

  2. Alternatively, using the jaws client container offers a more isolated setup.

  3. If you prefer direct integration with your existing Python projects, installing jaws-client package into your virtual environment is also an option.

1. module load jaws

You can use Environment Modules to load JAWS in the environment.

General Usage:

module use <PATH/jaws/modulefiles/>
module load jaws

Note

The purpose of module use is to point to our custom module files. You can add one or both of these lines to your ~/.bashrc file.

DORI
module use /clusterfs/jgi/groups/dsi/homes/svc-jaws/modulefiles/
module load jaws
PERLMUTTER
module use /global/cfs/projectdirs/jaws/modulefiles/
module load jaws
NMDC Project on PERLMUTTER

If you are part of NMDC project, please use:

module use /global/common/software/m3408/modulefiles/
module load jaws
NMDC Project on TAHOMA

If you are part of NMDC project on Tahoma, please use:

ssh twf2
module use /tahoma/mscnmdc/jaws-install/jaws-client/modulefiles/
module load jaws

  • To deactivate the environment, use the following:

    module unload jaws
Useful commands
module list        ## List actyive modules in the environment
module avail jaws  ## List available JAWS modules

2. JAWS Client Container

You can use the JAWS Client Container.

DORI
JAWS_USER_CONFIG=~/jaws.conf JAWS_CLIENT_CONFIG=/clusterfs/jgi/groups/dsi/homes/svc-jaws/dori-prod/jaws-prod.conf apptainer run docker://doejgi/jaws-client:latest jaws --help

  • Append to the end of your ~/.bashrc on DORI:

jaws() {
JAWS_USER_CONFIG=~/jaws.conf JAWS_CLIENT_CONFIG=/clusterfs/jgi/groups/dsi/homes/svc-jaws/dori-prod/jaws-prod.conf apptainer run docker://doejgi/jaws-client:latest jaws "$@"
}
PERLMUTTER
JAWS_USER_CONFIG=~/jaws.conf JAWS_CLIENT_CONFIG=/global/cfs/projectdirs/jaws/perlmutter-prod/jaws-prod.conf shifter --image=doejgi/jaws-client:latest jaws --help

  • Append to the end of your ~/.bashrc:

jaws() {
JAWS_USER_CONFIG=~/jaws.conf JAWS_CLIENT_CONFIG=/global/cfs/projectdirs/jaws/perlmutter-prod/jaws-prod.conf shifter --image=doejgi/jaws-client:latest jaws "$@"
}
NMDC Project on PERLMUTTER
JAWS_USER_CONFIG=~/jaws.conf JAWS_CLIENT_CONFIG=/global/common/software/m3408/nmdc-prod/jaws-prod.conf shifter --image=doejgi/jaws-client:latest jaws --help

  • Append to the end of your ~/.bashrc:

jaws() {
JAWS_USER_CONFIG=~/jaws.conf JAWS_CLIENT_CONFIG=/global/common/software/m3408/nmdc-prod/jaws-prod.confshifter --image=doejgi/jaws-client:latest jaws "$@"
}
NMDC Project on TAHOMA
JAWS_USER_CONFIG=~/jaws.conf JAWS_CLIENT_CONFIG=/tahoma/mscnmdc/jaws-install/jaws-client/nmdc_tahoma-prod/jaws-prod.conf apptainer run docker://doejgi/jaws-client:latest jaws --help

  • Append to the end of your ~/.bashrc:

jaws() {
JAWS_USER_CONFIG=~/jaws.conf JAWS_CLIENT_CONFIG=/tahoma/mscnmdc/jaws-install/jaws-client/nmdc_tahoma-prod/jaws-prod.conf  apptainer run docker://doejgi/jaws-client:latest jaws "$@"
}

3. Install jaws-client package into your virtual environment

  • Create gitlab token:

    • Go to https://code.jgi.doe.gov

    • In the upper-left corner, click on your avatar.

    • Select Edit profile.

    • On the left sidebar, select Access Tokens. And click create.

    • Enter a name and expiry date(i.e. never) for the token.

    • Select scopes:

      • read_api - Grants read access to the API, including all groups and projects, the container registry, and the package registry.

  • Back on your terminal (i.e. on Dori):

    • create a venv and activate it

    python3 -m venv <some-env-name>
source <some-env-name>/bin/activate

    • Install jaws-client package:

    pip install jaws-client --extra-index-url https://__token__:<your_personal_token>@code.jgi.doe.gov/api/v4/projects/312/packages/pypi/simple

    • Export variables (can be exported from inside ~/.bashrc)

    # these paths are for Dori. Ask jaws team for other sites.
JAWS_CLIENT_CONFIG=/clusterfs/jgi/groups/dsi/homes/svc-jaws/dori-prod/jaws-prod.conf
JAWS_USER_CONFIG=~/jaws.conf

  • Test the jaws command:

    jaws -h