-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* update for latest g3t making use of git * restructure page ordering and content structure for clarity * improve quickstart guide to cover data upload and data download use case * deprecate any mentions to `g3t utilities` * consolidate requirements page * incorporate initial user feedback --------- Co-authored-by: matthewpeterkort <[email protected]> Co-authored-by: quinnwai <[email protected]>
- Loading branch information
3 people
authored
Oct 21, 2024
1 parent
2da6405
commit 50187ac
Showing
14 changed files
with
410 additions
and
133 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,167 @@ | ||
| --- | ||
| title: Requirements | ||
| --- | ||
|
|
||
| # Requirements | ||
|
|
||
|
|
||
| {% include '/note.md' %} | ||
|
|
||
| ## 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](https://github.com/ACED-IDP/cdis-data-client/releases). Choose the file that matches your operating system (Windows, Linux, or macOS). | ||
|
|
||
| | Operating System | Gen3 Client | Checksum | | ||
| |------------------|------------------------------------------|----------------------------| | ||
| | macOS | [gen3-client-macos.pkg][macos] | [checksums.txt][checksums] | | ||
| | Linux (amd64) | [gen3-client-linux-amd64.zip][linux] | [checksums.txt][checksums] | | ||
| | Windows (amd64) | [gen3-client-windows-amd64.zip][windows] | [checksums.txt][checksums] | | ||
|
|
||
|
|
||
| [macos]: https://github.com/ACED-IDP/cdis-data-client/releases/latest/download/gen3-client-macos.pkg | ||
| [linux]: https://github.com/ACED-IDP/cdis-data-client/releases/latest/download/gen3-client-linux-amd64.zip | ||
| [windows]: https://github.com/ACED-IDP/cdis-data-client/releases/latest/download/gen3-client-windows-amd64.zip | ||
| [checksums]: https://github.com/ACED-IDP/cdis-data-client/releases/latest/download/checksums.txt | ||
|
|
||
| ### Checksum Verification | ||
|
|
||
| In order to verify that the downloaded file can be trusted checksums are provided in [`checksums.txt`][checksums]. See below for examples of how to use this file. | ||
|
|
||
| <details> | ||
| <summary>Successful Verification</summary> | ||
|
|
||
| To verify the integrity of the binaries on macOS run the following command in the same directory as the downloaded file: | ||
|
|
||
| ```sh | ||
| $ 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. | ||
|
|
||
| </details> | ||
|
|
||
| <details> | ||
| <summary>Unsuccessful Verification</summary> | ||
|
|
||
| Alternatively if the command outputs `FAILED` than the checksum did not match and the binary should not be run. | ||
|
|
||
| ```sh | ||
| $ 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. | ||
|
|
||
| </details> | ||
|
|
||
| ### Installation Instructions | ||
|
|
||
| ??? "macOS Installation Instructions" | ||
| 1. Download the latest macOS version ([dataclient_osx.pkg][macos]). | ||
| 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](https://aced-idp.org/identity). | ||
|
|
||
|  | ||
|
|
||
| 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: | ||
|
|
||
| ```sh | ||
| 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: | ||
|
|
||
| ```sh | ||
| 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](https://www.python.org/downloads/) 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: | ||
|
|
||
| ```sh | ||
| # 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](https://pypi.org/project/gen3-tracker/#history): | ||
|
|
||
| ```sh | ||
| g3t version | ||
| ``` | ||
|
|
||
| ### Upgrading g3t | ||
|
|
||
| This version should match the latest version on the [PyPi page](https://pypi.org/project/gen3-tracker/). If it is out of date, simply run the following to upgrade your local version: | ||
|
|
||
| ```sh | ||
| pip install -U gen3-tracker | ||
| ``` | ||
|
|
||
| ### Configuration | ||
|
|
||
| g3t uses the [gen3-client](https://gen3.org/resources/user/gen3-client/#2-configure-a-profile-with-credentials) 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 | ||
|
|
||
| ```sh | ||
| g3t ping | ||
|
|
||
| msg: 'Configuration OK: Connected using profile:production' | ||
| endpoint: https://aced-idp.org | ||
| username: [email protected] | ||
| ``` | ||
|
|
||
| Now that gen3-client and gen3-tracker are set up, see the [Quickstart Guide](/workflows/quick-start-guide) on how to upload data to a project. | ||
|
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -33,8 +33,7 @@ pip install -U gen3-tracker | |
|
|
||
| g3t uses the [gen3-client](https://gen3.org/resources/user/gen3-client/#2-configure-a-profile-with-credentials) configuration flow. | ||
|
|
||
| After configuration, you can either specify the `--profile` option or set the `G3T_PROFILE=profile-name` environmental variable. | ||
|
|
||
| After configuration, you can either specify the `--profile` or set the `G3T_PROFILE=profile-name` environmental variable. | ||
|
|
||
| ### Testing the configuration | ||
|
|
||
|
|
@@ -54,11 +53,13 @@ username: [email protected] | |
|
|
||
| The following options and environmental variables are synonymous, you may set them as environmental variables or pass them as parameters to the command line. | ||
|
|
||
| | option | environment | comment | example | | ||
| |--------------|-----------------| ------------------- | ------------------------------ | | ||
| | --project_id | G3T_PROJECT_ID | authorization | | | ||
| | --profile | G3T_PROFILE | gen3-client profile | | | ||
| | --format | G3T_FORMAT | Output format. | yaml | | ||
| | option | environment | comment | example | | ||
| | ------------ | -------------- | ------------------- | ------- | | ||
| | --project_id | G3T_PROJECT_ID | authorization | | | ||
| | --profile | G3T_PROFILE | gen3-client profile | | | ||
| | --format | G3T_FORMAT | Output format. | yaml | | ||
|
|
||
| For example, a `ping` command using the `aced` profile we be `g3t --profile aced ping` | ||
|
|
||
| Alternatively, you can set the environmental variables using the `EXPORT` function e.g.: | ||
|
|
||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,22 +2,25 @@ | |
|
|
||
| ## Granting user access to a project | ||
|
|
||
| Once a project has been created you will have full access to it. There are two ways to request the addition additional users to the project: | ||
| Once a project has been created you will have full access to it. | ||
| The project owner can add additional users to the project using the `g3t collaborator` commands. | ||
|
|
||
| There are two ways to request the addition additional users to the project: | ||
|
|
||
| ## 1. Read and Write Access | ||
|
|
||
| To give another user full access to the project, run the following: | ||
|
|
||
| ```sh | ||
| g3t utilities users add --username [email protected] --write --project_id aced-myproject | ||
| g3t collaborator add --write user-can-write@example.com | ||
| ``` | ||
|
|
||
| ## 2. Read Only Access | ||
|
|
||
| Alternatively, to give another user read access only (without the ability to upload to the project), run the following: | ||
|
|
||
| In order to implement these requests, **an authorized user will need to sign** the request before the user can use the remote repository. See `g3t utilities access sign` | ||
|
|
||
| ```sh | ||
| g3t utilities users add --username someone@example.com --project_id aced-myproject | ||
| g3t collaborator add user-read-only@example.com | ||
| ``` | ||
|
|
||
|
|
||
| ## 2. Approvals | ||
| In order to implement these requests, **an authorized user will need to sign** the request before the user can use the remote repository. See `g3t collaborator approve --help | ||
| ` | ||
Oops, something went wrong.