📘

PREREQUISITES:

• These instructions are part of the self-service pipeline documentation. To learn more, read the Self-Service Pipeline Overview before you begin.

These instructions explain how set up your environment, initialize the TetraScience Software Development Kit (TS SDK) and specify dependencies for your self-service pipeline project.

Set Up the Environment

To set up your environment, complete the following steps.

1. Install Python 3.7.x (We recommend using pyenv if you have to work with multiple versions on the same machine.)

📘

NOTE:

You can also use Python 3.8.x or 3.9.x instead of 3.7.x. If you do use those versions, new features introduced in 3.8 or afterward should not be used.

2. Install pipenv: pip3 install pipenv.
3. Install ts-sdk package: pip3 install ts-sdk.
4. Check if the installation was successful by running ts-sdk --help.
5. Log into the TDP as an admin user.
6. Generate a service user with admin access on the “organization” page in your profile (or use an existing one).
7. Generate a service token for the service user you have selected.
8. Create a cfg.json file (you may select a different name) at any location you want. You can also download it from the previous step by clicking the "Download ts-sdk config" button on the token creation modal. You will use this file later in the ts-sdk put command by adding -c path/to/cfg.json to the command line. This is what the configuration JSON file will look like:

{
    "api_url":"<TDP API endpoint base URL>",
    "auth_token":"<service token you generated>",
    "org":"<your organization slug name>",
    "ignore_ssl": <true to allow invalid SSL certificates>
}

📘

NOTE:

• If your TDP URL is https://xxx.tetrascience.com, then the API URL is usually https://api.xxx.tetrascience.com/v1. The API endpoint is usually in the form: https://api.{TDP-DOMAIN}/v1.

• These configs can be overridden by environment variables (with TS_ prefix, i.e.: TS_API_URL) or command-line arguments (--api-url, --auth-token, --org, --ignore-ssl). Command-line arguments have the highest priority.

Initialize the TS SDK and Specify Dependencies

To initialize the TS SDK and specify dependencies, do the following.

🚧

AUTO-GENERATED SCRIPTS:

ts-sdk init will create some template script files for you and they are fully functional (including test files). So you can deploy them to test self-service pipeline feature. You will learn more about what the script does from Script Walkthrough section in the next step. But let's finish this step first.

1. Use ts-sdk init command to create a new folder, with a sample task script and protocol based on a simple template. (Use ts-sdk init --help to get more information about available arguments).

ts-sdk init --org <your organization slug name> -p <protocol slug> -t <task script slug> -f <folder name for the generated code>
# e.g. the following will generate folder `./decorate`,
# which contains protocol folder (identified by slug "my-protocol") and task-script folder (identified by slug "ts"):
# $ ts-sdk init -p my-protocol -t ts --org tetrascience-demo-1 -f ./decorate

📘

NOTE:

To better understand how slugs are used with Self-Service Pipeline, read the Slugs and Self-Service Pipelines topic.

2. Install the dev dependencies.

# Go to the newly created task-script folder
cd path/to/the/task-script-folder
pipenv install --dev

# (optional) install additional packages if your script uses any
pipenv install numpy pandas [...]

3. If you need to use private packages you can install them from two places:

• The local archive
• The local *.whl (wheel) file

Both of these are discussed in the Python Packaging User Guide's Installation Packages topic.

4. Generating distribution archives instructions can be found in the Python Packaging User Guide's tutorial for packaging projects.

pipenv install ./task-script-folder/private-pkg-1.0.4.tar.gz
# or
pipenv install ./task-script-folder/private-pkg-1.0.4.whl

Note: the archive should be placed inside the task script folder (it has to be uploaded with the task script code).