Requirements

Note

The tools listed here are under development and may be subject to change

1. Download gen3-client

A binary executable of the latest version of the gen3-client should be downloaded from the following Table or from the Release page on Github. Choose the file that matches your operating system (Windows, Linux, or macOS).

Operating System	Gen3 Client	Checksum
macOS	gen3-client-macos.pkg	checksums.txt
Linux (amd64)	gen3-client-linux-amd64.zip	checksums.txt
Windows (amd64)	gen3-client-windows-amd64.zip	checksums.txt

Checksum Verification

In order to verify that the downloaded file can be trusted checksums are provided in checksums.txt. See below for examples of how to use this file.

Successful Verification

To verify the integrity of the binaries on macOS run the following command in the same directory as the downloaded file:

$ shasum -c checksums.txt --ignore-missing
gen3-client-macos.pkg: OK

If the `shasum` command outputs `OK` than the verification was successful and the executable can be trusted.

Unsuccessful Verification

Alternatively if the command outputs `FAILED` than the checksum did not match and the binary should not be run.

$ shasum -c checksums.txt --ignore-missing
shasum: WARNING: 1 computed checksum did NOT match
shasum: checksums.txt: no file was verified

In such a case please reach out to the ACED development team for assistance.

Installation Instructions

macOS Installation Instructions

1. Download the latest macOS version (dataclient_osx.pkg).
2. Follow the instructions in the installer
3. Open a terminal window.
4. Move the executable to the default directory: mv /Applications/gen3-client ~/.gen3/gen3-client
5. Add the directory containing the executable to your Path environment variable by entering this command in the terminal: echo 'export PATH=$PATH:~/.gen3' >> ~/.bash_profile
6. Run source ~/.bash_profile or restart your terminal.
7. Now you can execute the program by opening a terminal window and entering the command gen3-client

Linux Installation Instructions

1. Download the latest Linux version of the gen3-client.
2. Unzip the archive.
3. Add the unzipped executable to a directory, for example: ~/.gen3/gen3-client
4. Open a terminal window.
5. Add the directory containing the executable to your Path environment variable by entering this command in the terminal: echo 'export PATH=$PATH:~/.gen3' >> ~/.bash_profile
6. Run source ~/.bash_profile or restart your terminal.
7. Now you can execute the program by opening a terminal window and entering the command gen3-client

Windows Installation Instructions

1. Download the Windows version of the gen3-client.
2. Unzip the archive.
3. Add the unzipped executable to a directory, for example: C:\Program Files\gen3-client\gen3-client.exe
4. Open the Start Menu and type "edit environment variables".
5. Open the option "Edit the system environment variables".
6. In the "System Properties" window that opens up, on the "Advanced" tab, click on the "Environment Variables" button.
7. In the box labeled "System Variables", find the "Path" variable and click "Edit".
8. In the window that pops up, click "New".
9. Type in the full directory path of the executable file, for example: C:\Program Files\gen3-client
10. Click "Ok" on all the open windows and restart the command prompt if it is already open by entering cmd into the start menu and hitting enter.

2. Configure a Profile with Credentials

Before using the gen3-client to upload or download data, the gen3-client needs to be configured with API credentials downloaded from the Profile page.

Download the access key from the portal and save it in the standard location ~/.gen3/credentials.json

From the command-line, run the gen3-client configure command:

gen3-client configure --profile=<profile_name> --cred=<credentials.json> --apiendpoint=https://aced-idp.org

# Mac/Linux Example:
gen3-client configure --profile=demo --cred=~/Downloads/credentials.json --apiendpoint=https://aced-idp.org

# Windows Example:
gen3-client configure --profile=demo --cred=C:\Users\demo\Downloads\credentials.json --apiendpoint=https://aced-idp.org

To confirm you successfully configured a profile with the correct authorization privileges, you can run the gen3-client auth command, which should list your access privileges for each project in the commons you have access to:

gen3-client auth --profile=aced

# 2023/12/05 15:07:12
# You have access to the following resource(s) at https://aced-idp.org:
# 2023/12/05 15:07:12 /programs/aced/projects/myproject...

3. Install gen3-tracker (g3t)

The gen3-tracker (g3t) tool requires a working Python 3 installation no older than Python 3.10. Run the following in your working directory to install the latest version of g3t from the Python Package Index:

# Optionally create a virtual environment
python3 -m venv venv; source venv/bin/activate

pip install gen3-tracker

You can verify the installation was successful by then running the g3t command with the expected output being the latest version:

g3t version

Upgrading g3t

This version should match the latest version on the PyPi page. If it is out of date, simply run the following to upgrade your local version:

pip install -U gen3-tracker

Configuration

g3t uses the gen3-client configuration flow.

After configuration, you can either specify the --profile or set the G3T_PROFILE=profile-name environmental variable.

Testing the configuration

The command g3t ping will confirm that the access key and gen3-client have been configured correctly

g3t ping

msg: 'Configuration OK: Connected using profile:production'
endpoint: https://aced-idp.org
username: someone@example.com

Now that gen3-client and gen3-tracker are set up, see the Quickstart Guide on how to upload data to a project.