updates to the getting started docs

Author: wjallen

docs/01.01.request_access.md

@@ -0,0 +1,35 @@
+---
+layout: page
+title: Request Access to the SD2E Platform
+tagline:
+---
+
+#### SD2E Access
+Access is restricted to SD2 project members. Your username and password will be
+the same as your TACC username and password. To gain access, please follow the
+instructions on this page:
+
+[Request SD2E Access](https://sd2e.org/accounts/request-access/)
+
+Note: If you are already logged in to SD2E.org, you will have to first logout
+by [clicking here](https://sd2e.org/accounts/logout), then retry the link above.
+Account confirmation may take up to 1-2 business days.
+
+<br>
+#### GitLab
+Depending on how you plan to interact with and use the SD2E platform, you may
+also need access to the [SD2E Gitlab](https://gitlab.sd2e.org/). Once your TACC
+account and SD2E access are confirmed, request access to Gitlab by posting in
+the `#cyberinfrastructure` channel of the
+[SD2E Team Slack](https://sd2e.slack.com/messages).
+
+<br>
+#### Docker Hub
+Several components of the SD2E platform utilize Docker images. To make full use
+of this platform, create a personal [Docker Hub account](https://hub.docker.com/)
+if you do not have one already.
+
+
+
+---
+Return to the [API Documentation Overview](../index.md)

docs/install_cli.md renamed to docs/01.02.install_cli.md

@@ -4,18 +4,30 @@ title: Install and Configure the CLI
 tagline:
 ---
 
-The primary method for interacting with the SD2E platform is the 
-[Agave command line interface (CLI)](https://agaveapi.co/).
-The CLI is a collection of ~150 shell scripts for managing
-authorization, files, systems, applications, jobs, and more. 
+The primary method for interacting with the SD2E platform is the
+[SD2E command line interface (CLI)](https://github.com/SD2E/sd2e-cli).
+The CLI is a collection of ~150 shell scripts and other resources for managing
+authorization, files, systems, applications, jobs, and more.
 
-There are three methods to install the CLI:
+There are three methods to install the CLI, choose whichever fits your preferred
+working environment:
 1. Run an installer script to install in ~/sd2e-cloud-cli/bin/
 2. Manual install to a location of your choosing
 3. Pull a CLI Docker image
 
 <br>
-#### Run an installer script to install in ~/sd2e-cloud-cli/bin/
+#### Requirements
+
+Make sure in your environment, you have:
+1. [Bash](https://www.gnu.org/software/bash/)
+2. [cURL](https://curl.haxx.se/)
+3. [Git](https://git-scm.com/)
+4. [Docker](https://www.docker.com/get-docker)
+5. [jq](https://stedolan.github.io/jq/)
+6. [python 2.7+ or 3.x+](https://www.python.org/downloads/)
+
+<br>
+#### Install method 1: Run an installer script to install in `~/sd2e-cloud-cli/bin/`
 
 Open a terminal window and run the installer script:
 ```
@@ -41,7 +53,7 @@ TACC Cloud API versions:
 ```
 
 <br>
-#### Manual install to a location of your choosing
+#### Install method 2: Manual install to a location of your choosing
 
 Open a terminal window and navigate to your preferred location for installation:
 
@@ -51,7 +63,8 @@ Open a terminal window and navigate to your preferred location for installation:
 
 Download and unpack the CLI:
 ```
-% curl -L https://raw.githubusercontent.com/sd2e/sd2e-cli/master/sd2e-cloud-cli.tgz -o sd2e-cloud-cli.tgz
+% curl -L https://raw.githubusercontent.com/sd2e/sd2e-cli/master/sd2e-cloud-cli.tgz \
+       -o sd2e-cloud-cli.tgz
 % tar -xvzf sd2e-cloud-cli.tgz
 ```
 
@@ -74,7 +87,7 @@ TACC Cloud API versions:
 ```
 
 <br>
-#### Pull a CLI Docker image
+#### Install method 3: Pull a CLI Docker image *(outdated)*
 
 The CLI is also available as a Docker image. For this to work, it is assumed you
 have a reasonably recent version of [Docker](https://www.docker.com/) installed.
@@ -99,15 +112,23 @@ TACC Cloud API versions:
 <br>
 #### Influential environment variables
 
+When working with the SD2E platform, you may optionally set some of the following
+environment variables. In bash, it will take the form:
+```
+% export VAR_NAME=option
+e.g.
+% export AGAVE_JSON_PARSER=jq
+```
+
 <table style="width:100%" border="1px" cellpadding="5">
   <tr>
-    <th align="left">environment variable</th>
-    <th align="left">options</th>
-    <th align="left">description</th>
+    <th align="left">Environment variable</th>
+    <th align="left">Options</th>
+    <th align="left">Description</th>
   </tr>
   <tr>
     <td>AGAVE_JSON_PARSER</td>
-    <td>json_mirror, jq, json, python, native</td>
+    <td>jq, json_mirror, json, python, native</td>
     <td>Set this to your favorite json parser (if installed)</td>
   <tr>
   </tr>

docs/create_client.md renamed to docs/01.03.create_client.md

@@ -4,14 +4,15 @@ title: Create the Client API Keys
 tagline:
 ---
 
-The Agave CLI is used to configure your user environment to interact with the 
-SD2E platform. If you do not yet have the CLI installed and in your `$PATH`, first
-go [here](install_cli.md).
+[The Agave API](http://developer.tacc.cloud/), (a component of the SD2E API), is
+used to configure your user environment to interact with the SD2E platform. If
+you do not yet have the CLI installed and in your `$PATH`, first go
+[here](01.02.install_cli.md) to install it.
 
 <br>
 #### Initiate with the SD2E Agave tenant
 
-On the command line, perform: 
+On the command line, perform:
 ```
 % tenants-init -t sd2e
 
@@ -24,7 +25,7 @@ home directory: `~/.agave/current`
 <br>
 #### Create API keys
 
-API keys are used to authenticate and store your user credentials for a specific 
+API keys are used to authenticate and store your user credentials for a specific
 client application. To generate API Keys:
 ```
 % clients-create -S -N sd2e_client -D "My client used for interacting with SD2E"
@@ -60,7 +61,7 @@ can delete then regenerate client API keys with the following:
 ```
 
 <br>
-#### The ~/.agave/current configuration file
+#### The `~/.agave/current` configuration file
 
 In addition to the tenant ID, your API keys are stored in the Agave configuration
 file. To view the contents of the file:

docs/authorization.md renamed to docs/01.04.authorization.md

@@ -11,7 +11,7 @@ for generating their own authorization tokens and, optionally, saving them in th
 <br>
 #### Generate authorization token
 
-Generate a token with the following command (the `-S` flag stores the token in 
+Generate a token with the following command (the `-S` flag stores the token in
 your Agave configuration file):
 ```
 % auth-tokens-create -S

docs/ssh_keys.md renamed to docs/01.05.ssh_keys.md

@@ -5,15 +5,15 @@ tagline:
 ---
 
 In certain circumstances, it is advantageous to use public / private SSH keys
-to authenticate with Agave. Specifically, this is important when
-[creating your own private systems](create_systems.md). Having SSH keys will make it 
-easier to interact with systems that do not allow password authentication or that
-require frequent password changes, and it will increase security by preventing
-the need to store your password in a plain text file.
+to authenticate with the Agave API. Specifically, this is important when
+[creating your own private systems](02.06.create_systems.md). Having SSH keys
+will make it easier to interact with systems that do not allow password
+authentication or that require frequent password changes, and it will increase
+security by preventing the need to store your password in a plain text file.
 
 If you are new to the Agave CLI and the SD2E Agave tenant, it is recommended to
 skip this section of the documents until you need to
-[create your own private systems](create_systems.md).
+[create your own private systems](02.06.create_systems.md).
 
 <br>
 #### Prerequisites
@@ -40,7 +40,7 @@ Welcome to
  / ___ \ |_| | | | | | (_) \__ \ |_) | | | |  __/ | |  __/
 /_/   \_\__|_| |_| |_|\___/|___/ .__/|_| |_|\___|_|  \___|
                                |_|
-[js-104-39] % 
+[js-104-39] %
 ```
 
 <br>
@@ -76,8 +76,8 @@ Finally, add your public key to the `authorized_keys` file on your remote system
 [js-104-39] % cat agave_rsa.pub >> ~/.ssh/authorized_keys
 ```
 Your private key (`agave_rsa`) will be used in the future when it is time to
-[create your own private systems](create_systems.md). Never share your private
-key with anyone else.
+[create your own private systems](02.06.create_systems.md). Never share your
+private key with anyone else.
 
 
 ---

docs/request_access.md

@@ -13,15 +13,15 @@ the SD2E platform. Documentation for getting started with the SD2E API is below.
 
   **1 Getting Started**
 
-    1.1 [Request Access to the SD2E Platform](docs/request_access.md)
+    1.1 [Request Access to the SD2E Platform](docs/01.01.request_access.md)
 
-    1.2 [Install and Configure the SD2E CLI](docs/install_cli.md)
+    1.2 [Install and Configure the SD2E CLI](docs/01.02.install_cli.md)
 
-    1.3 [Create the Client API Keys](docs/create_client.md)
+    1.3 [Create the Client API Keys](docs/01.03.create_client.md)
 
-    1.4 [Authorize with the SD2E Tenant](docs/authorization.md)
+    1.4 [Authorize with the SD2E Tenant](docs/01.04.authorization.md)
 
-    1.5 [SSH Key Pairs](docs/ssh_keys.md)
+    1.5 [SSH Key Pairs](docs/01.05.ssh_keys.md)
 
 
   **2 Agave CLI Basics**
@@ -83,6 +83,7 @@ the SD2E platform. Documentation for getting started with the SD2E API is below.
 
 
   **6 Placeholder**
+
   **7 Reference Pages**
 
 
@@ -94,4 +95,4 @@ You can get more help by visiting the main [SD2E website](http://sd2e.org), or
 e-mailing us at `support-at-sd2e-dot-org`.
 
 Please visit the [Developer Documentation for TACC Cloud APIs](https://tacc.github.io/developer.tacc.cloud/)
-site for additional API support. 
+site for additional API support.