Merge pull request #3 from JStover95/JStover95/tutorial-revisions

Tutorial Revisions

Author: renatof

.gitignore

@@ -0,0 +1 @@
+.venv/

docs/credentials.md

@@ -1,9 +1,8 @@
 # Creating cloud credentials
 
-
 ## S3 data server
 
-- In general, the credentials you need from your S3 account are the `AccessKey` and the `SecretKey`. These are akin to user names and passwords. 
+- In general, the credentials you need from your S3 account are the `AccessKey` and the `SecretKey`. These are akin to user names and passwords.
 - How you obtain these credentials will depend on your provider (e.g. AWS S3, MINIO, OSN - see below)
 - Paste the access key and the secret key as _Repository secrets_ in your _FaaSr-workflow_ as per the instructions in the [workflow repo] documentation
 
@@ -13,6 +12,7 @@ If you don't already have one, you need to generate a GitHub Personal Access Tok
 [Details on how to create a PAT are available here](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic)
 
 In summary:
+
 - In the upper-right corner of any page, click your profile photo, then click Settings.
 - In the left sidebar, click Developer settings.
 - In the left sidebar, click Personal access tokens.
@@ -29,14 +29,12 @@ In summary:
 - Paste the access key and the secret key under the names `AWS_AccessKey` and `AWS_SecretKey`, respectively, as _Repository secrets_ in your _FaaSr-workflow_ as per the instructions in the [workflow repo] documentation
 - Paste your ARN as `AWS_ARN` as _Repository secrets_ in your _FaaSr-workflow_
 
-
 ## OpenWhisk
 
 - You need an API key from your provider to configure for use in FaaSr
 - How you obtain this will depend on your cloud provider.
 - Paste the API key under the name `OW_APIkey` as a _Repository secret_ in your _FaaSr-workflow_ as per the instructions in the [workflow repo] documentation
 
-
 ## Google Cloud Platform
 
 - You need a private secret key to use Google Cloud Platform (GCP) with FaaSr
@@ -54,5 +52,4 @@ TBD
 - For researchers in the US, you can [request an allocation](https://www.openstoragenetwork.org/get-involved/get-an-allocation/) of 10+ TB S3 storage.
 - If your request is approved, you will be assigned one S3 bucket, and can then copy the access and secret keys provided to you for use with FaaSr
 
-
 [workflow repo]: workflow_repo.md

docs/tutorial.md

@@ -1,6 +1,10 @@
 # Tutorial
 
-This document guides you through a simple tutorial that uses GitHub Actions and a free S3 data store (Minio Play). The pre-requisite for this tutorial is a GitHub account.
+This document guides you through a simple tutorial that uses GitHub Actions and a free S3 data store (Minio Play).
+
+## Prerequisites
+
+For this tutorial, all you need is a GitHub account. It is also recommended that your refer to the [Setting up the FaaSr-workflow repo](./workflow_repo.md) documentation for details about the FaaSr-workflow repository.
 
 ## Configure your FaaSr-workflow repository
 
@@ -12,13 +16,16 @@ This is a one-time step you go through to set up your [workflow repository] to h
 
 ## Configure your GitHub PAT
 
-You need a personal access token in your repository secrets to run this tutorial. 
+You need a personal access token in your repository secrets to run this tutorial.
 
-Follow the steps outlined in the [credentials] documentation to obtain your PAT. Copy this PAT so you can paste it as a secret in the next step
+Follow the steps outlined in the [GitHub Actions credentials] documentation to obtain your PAT. Copy this PAT so you can paste it as a secret in the next step
 
 ## Configure your repository secrets
 
-Before you can register and invoke workflows, you need to create secrets storing credentials for the cloud providers you will use. The following assumes that you already have obtained [cloud credentials] for those.
+Before you can register and invoke workflows, you need to create secrets storing credentials for the cloud providers you will use.
+
+!!! note "Guest S3 Credentials"
+    Note that for this tutorial we are using guest credentials for a free S3 data store offered by MinIO. In practice, you will use your own credentials (see the [credentials](./credentials.md) documentation for more information).
 
 - In the _FaaSr-workflow_ repo you just forked, click on the _Settings_ tab (top of the page, to the right)
 - Scroll down; on the left pane, click on the pull-down _Secrets and variables_ and select _Actions_
@@ -56,7 +63,13 @@ The tutorial.json file is available in the FaaSr-Functions repository; you will
 
 ## Invoke the workflow
 
-- After register, you can [invoke the workflow] 
+!!! question "What code am I running?"
+    For this tutorial, function code is sourced from the [FaaSr-Functions](https://github.com/FaaSr/FaaSr-Functions) repository. See [Creating Functions](./functions.md) for more information on how FaaSr runs function code.
+
+!!! warning
+    Run only [workflows and code that you trust](./security.md#only-reuse-workflowsfunctions-that-you-trust) with FaaSr. Always check that you trust the provenance of the workflow or code that you are running.
+
+- After register, you can [invoke the workflow]
 - Click on _Actions_
 - Click on `(FAASR INVOKE)` (left)
 - Click on the `Run workflow` drop-down; enter `tutorial.json` and click on `Run workflow`
@@ -83,9 +96,8 @@ The tutorial.json workflow is based on two R functions (start, compute_sum). Ano
 - `(FAASR REGISTER)` tutorialRpy.json
 - `(FAASR INVOKE)` tutorialRpy.json
 
-
 [workflow repository]: workflow_repo.md
-[credentials]: credentials.md
+[GitHub Actions credentials]: credentials.md#github-actions
 [FaaSr Workflow Builder Web UI]: https://faasr.io/FaaSr-workflow-builder/
 [register the workflow]: register_workflow.md
 [invoke the workflow]: invoke_workflow.md

mkdocs.yml

@@ -10,8 +10,7 @@ nav:
   - 'Tutorial': 'tutorial.md'
   - 'Documentation':
     - 'FaaSr workflow model': 'prog_model.md'
-    - 'Tutorial': 'tutorial.md'
-    - 'Setting up FaaSr-workflow repo': 'workflow_repo.md'
+    - 'Setting up the FaaSr-workflow repo': 'workflow_repo.md'
     - 'Creating functions': 'functions.md'
     - 'Creating and editing workflows': 'workflows.md'
     - 'Example workflows and functions': 'functionexamples.md'
@@ -31,4 +30,7 @@ nav:
   - 'About': 'about.md'
   - 'Community': 'community.md'
   - 'Contact': 'contact.md'
-  
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences