Tooling documentation

Tooling/README.md

@@ -0,0 +1,68 @@
+# Tooling
+
+This folder contains supporting scripts to automate the serverless backend resource creation/updating.
+
+
+## Scope
+The scripts here will create and update AWS Lambdas and their paired API Gateways as well as attaching appropriate IAM roles to the Lambdas and Cognito integration to the API Gateway.
+
+Covered:
+ - AWS Lambdas
+ - AWS API Gateway
+ - AWS IAM <-> AWS Lambda interaction
+ - AWS Cognito <-> API Gateway interaction
+ 
+Not covered:
+ - Verification of Lambda correctness: These scripts will in no way verify that the built jar is correct.
+ 
+
+
+## Files
+
+#### EndpointSetup.sh
+  - Purpose: Creates a new AWS Lambda, and, if needed, a new API Gateway endpoint and HTTP method on the endpoint. The names are autogenerated based on the method and the input name.
+  - Inputs:
+    - Resource name: Name of the resource (e.x. List).
+    - HTTP method: HTTP method to use to access this particular Lambda. Will be appended to resource name to get expected Java class (e.x. resourceGET)
+    - Resource jar: The script will search the project directory for a jar with the given resource name (resource.jar). The jar should contain all method classes for the resource as well as any dependencies.
+    
+#### LambdaUpdate.sh
+  - Purpose: Refreshes the jar attached to a specific Lambda.
+  - Inputs:
+    - Resource name: Name of the resource (e.x. List).
+    - HTTP method: HTTP method to use to access this particular Lambda. Will be appended to resource name to get expected Java class (e.x. resourceGET)
+    
+#### VarSetup.sh
+ - Purpose: Sets up some constants related to the AWS account and basic resources (e.x. broad API gateway id, Cognito pool). Collects constants for easy modification
+ 
+ 
+ 
+ 
+## Running
+ 
+```
+$ bash Tooling/EndpointSetup.sh 
+Creating a Gateway/Lambda pair.
+Please enter base function name: List
+Please enter method(GET, POST, etc.): PUT
+
+```
+
+```
+$ bash Tooling/LambdaUpdate.sh 
+Updating a Lambda.
+Please enter base function name: List
+Please enter method(GET, POST, etc.): PUT
+Update successful.
+```
+
+VarSetup.sh should not need to be called directly since the other scripts `source` it.
+ 
+## Debugging
+ 
+ VarSetup.sh has a `DEBUGFILE` constant in it. By default it is `/dev/null`, but you can change it to something else to get debugging output.
+ 
+## Notes
+- Many configurations are stored as constants in the scripts and can be modified. Most of these constants should be in VarSetup.sh, but some may be elsewhere.
+- Sometimes the allocated memory and/or runtime is insufficient and must be adjusted upwards.
+- If in Windows Subsystem for Linux, you may have to remove '\r' characters that Windows added to the .sh files.