Deriva Clients

DERIVA client tools

The DERIVA client tools are used for authenticating to the FaceBase server, bulk uploading of data, and bulk downloading of data. We provide both graphical desktop clients and command-line interface clients.

• DERIVA desktop clients (Windows or macOS)
  • DERIVA-Auth: a desktop client for establishing an authentication token.
  • DERIVA-Upload: a desktop client for uploading data files.
• DERIVA Python command-line clients (Python 2.7+ or 3.x)
  • deriva-upload-cli: a command-line utility for uploading data files.
  • deriva-download-cli: a command-line utility for downloading data files.

Which client to install and use?

• If you are submitting data to FaceBase, and your files are accessible to your desktop computer:
  • Install DERIVA-Upload on your desktop computer
• If you are submitting data to FaceBase, and your files are on a server/cluster/remote computer:
  • Install DERIVA-Auth on your desktop computer
  • And install DERIVA Python (deriva-py) on the server/cluster/remote computer

Installing DERIVA-Auth and/or DERIVA-Upload (Desktop clients)

The DERIVA-Upload and DERIVA-Auth clients are packaged as apps for Mac and Windows computers.

System Requirements

• macOS, or
• Windows

Installation steps

1. Go to the Deriva Authentication Agent and Upload Utility (0.4.4) release page.
2. Download the DERIVA-Upload-0.4.4-{osx|win}.zip and/or DERIVA-Auth-0.4.4-{osx|win}.zip file for your platform (Windows or macOS).
3. Unzip the zip file.
4. Copy the application to your file system:
   • On Windows, drag the ".exe" file to some location (e.g., your desktop or documents folder)
   • On Mac, drag the app file to some location (e.g., applications folder under your home directory)

Mac users: macOS generally prevents applications from opening that were not downloaded from the Apple App Store or from 'signed developers'. To open the application, find it in the Mac Finder, right-click on it, and click 'open'. If prompted, confirm that you want to open the application.

Installing DERIVA Python (CLI utilities)

The deriva-upload-cli and deriva-download-cli are installed from their Python deriva-pysoftware source package.

System Requirements

• Python 2.7+ or 3.x, which is usually installed by default on macOS or Linux based systems;
• Python virtual environment (recommended but not required).

Installation steps

1. Go to the DERIVA Python (0.4.4) release page.
2. Download the 'Source code' package of your choice (.zip or .tar.gz)
3. Unzip it, for example

   $ tar zxf 0.4.4.tar.gz
   

4. If you are using a Python virtual environment, activate it now. Here we assume you have created a virtual environment named deriva-env. You can install deriva without using a virtual environment.

   $ source deriva-env/bin/activate
   

5. Install deriva-py using the Python pip utility.

   (deriva-env) $ cd deriva-py-0.4.4
   (deriva-env) $ pip install .
   

   • if you do not have pip, you could run python setup.py install instead.

Authentication Tokens

The deriva-upload-cli and deriva-download-cli utilities require an authentication token, so you must be able to install and run the desktop DERIVA-Auth utility on a Windows or macOS desktop even if you plan to upload/download data files using the CLI from another server. The CLI can be run remotely from the DERIVA-Auth.

Most likely if you are transferring large files to/from a cluster, you will run DERIVA-Auth on your local desktop to establish and maintain the authentication token, while you run the deriva-upload-cli or deriva-download-cli from your cluster just passing it the authentication token that you established with DERIVA-Auth as a parameter when you invoke the CLI.

DO NOT SHARE YOUR TOKEN

The authentication token is equivalent to a short-term, temporary password, in simple terms. Treat it as you would your FaceBase username and password.

• Do not share it with anyone.
• Do not copy and paste it into an email.

Authentication Token Lifetime

The authentication token will expire in 30 minutes by default. However, the DERIVA-Auth client will refresh the token so long as you leave the DERIVA-Auth client open and running on your desktop.

For long transfers, keep the authentication agent running on your local system while the remote transfer is in progress. If you close the DERIVA-Auth client, any ongoing transfers (past the 30 minute limit) will fail and report 'not authorized' errors.

Establish an Authentication Token

1. Open the DERIVA-Auth application
2. First time use:
   • In the "Server:" input box enter www.facebase.org
   • Click Add
3. Subsequent use:
   • Ensure that the "Server:" field indicates www.facebase.org
   • Click Login
4. Follow the prompts in the main panel to login
5. Copy the "bearer" token:
   • Click "Show Token"
   • Click "Show Details..."
   • Copy the token
   • Click "Close"

If there are any errors, they should be reported in the status panel beneath the file listing panel.

Terminate an Authentication Token

When you are finished using the authentication token, click "Logout" and exit the application. When you do this, the token will be invalidated immediately.