update docs

gugzkumar · Jan 1, 2020 · 4cd7d8c · 4cd7d8c
1 parent f211907
commit 4cd7d8c
Show file tree

Hide file tree

Showing 5 changed files with 33 additions and 19 deletions.
diff --git a/docs/other-docs.md → docs/gained-learnings.md b/docs/other-docs.md → docs/gained-learnings.md
@@ -1,4 +1,5 @@
-
+# Gained Learnings
+This is a list of things I've learned, primarily about Serverless, that happened while building this App. Originally coming from a container orchestration background, it's interesting to compare the advantages and disadvantages approaches.
 
 https://github.com/awslabs/aws-support-tools/blob/master/Cognito/decode-verify-jwt/decode-verify-jwt.py
 Doesn't break whole API

diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -3,16 +3,24 @@
 This document and the following ones will help you set up Cheet Sheet.
 
 ### Preliminary Setup
-Click [here](/docs/setup.md) to read the necessary prep to run the app locally and deploy it AWS.
+Click [here](/docs/setting-up-preliminary-tools.md) to read the necessary prep to run the app locally and deploy it AWS.
 
 ### Set Up and Run Locally
-Click [here](/docs/set-up-locally.md) to learn how to setup and run the app on your local machine. This is good for development and testing.
+Click [here](/docs/setting-up-locally.md) to learn how to setup and run the app on your local machine. This is good for development and testing.
 
 ### Set Up and Deploy to AWS
-Click [here](/docs/set-up-remote.md) to learn how to setup and deploy the app to the cloud so that you and others can use it in real life.
+Click [here](/docs/setting-up-remote.md) to learn how to setup and deploy the app to the cloud so that you and others can use it in real life.
+
+### Set Up Continuous Deployment
+Click [here](/docs/setting-up-ci-cd.md) to learn how to setup continuous deployment through CircleCI. This will automate deployment of changes to the API and UI, so that effort can be focused on designing new features rather than launching them.
+
+### Environment Variable Glossary
+Click [here](/docs/environment-variable-glossary.md) to learn what the different Environment variables in the app are.
+
+<!-- # Other Useful Documents
 
 ### Architecture Overview
 
 ### Environment Variable Glossary
 
-### Questions and Answers
+### Gained Learnings -->
diff --git a/docs/setting-up-locally.md b/docs/setting-up-locally.md
@@ -1,5 +1,6 @@
 # Setting Up And Running The App On Your Local Machine
 
+This guide is for you to have a working version of Cheet Sheet deployed to your machine. This is useful for testing the app before you use it, and develop new features. All commands, unless otherwise noted, should be ran from the root of the project folder.
 
 ## Create Your infrastructure.env File
 
@@ -10,9 +11,9 @@
 3. Confirm you now have a file in your root folder called `infrastructure.env`
 
 <details><summary>What just happened?</summary>
-<p>
-    To be written
-</p>
+
+> The first thing we need to do is provision infrastructure for the app. This includes things like S3 Buckets, Cognito Userpools. We do this through docker compose. The file called infrastructure.env, is what properly configures how to build the infrastructure. You could also build the `infrastructure.env` file manually by following the [infrastructure.template.env](/.env_templates/infrastructure.template.env).  It's just that the utility cli provides guided prompts to make it a bit easier. *If you want to learn more about what each configuration is, read the ENVIRONMENT variable glossary.*
+
 </details>
 
 ## Build AWS Infrastructure
@@ -28,9 +29,13 @@
 1. Run `docker-compose -f docker-compose.deploy.infrastructure.yml down -v` to take down the infrastructure deploy environment
 
 <details><summary>What just happened?</summary>
-<p>
-    To be written
-</p>
+
+> Infrastructure is provisioned via the AWS CDK. This is an open-source Infrastructure as Code toolkit for AWS that streamlines creating and applying changes to infrastructure. We first use docker compose to create a docker container with the CDK installed and infrastructure templates defined. Next we exec in to the container (this is similar to ssh'ing into a vm) to run CDK cli commands inside it that build and deploy our AWS Cloudformation Infrastructure Stack. We user docker for 2 reasons:
+> 1. It makes the number of things you have to install less
+> 2. We can version control dependencies to reduce possibility of breaking changes
+>
+> **Note:** Because this is only mean to run locally on our machine do only things we need are Cognito and an S3 bucket for app data, unlike in **Setting Up And Launching The App On AWS**, where we need more.
+
 </details>
 
 ## Create Your .env File
@@ -39,9 +44,9 @@
 1. Confirm you now have a file in your root folder called `.env`
 
 <details><summary>What just happened?</summary>
-<p>
-    To be written
-</p>
+
+> Now that we have a Cognito Userpool and an S3 bucket created from the previous step, can run our app locally. The file called `.env`, is what properly configures things to run on your machine. You could also build the `.env` file manually by following [local.template.env](/.env_templates/local.env). It's just that the utility cli provides guided prompts to make it a bit easier. *If you want to learn more about what each configuration is, read the ENVIRONMENT variable glossary.*
+
 </details>
 
 ## Running the App
@@ -54,7 +59,7 @@
 1. Run `docker-compose down -v` to take down the app
 
 <details><summary>What just happened?</summary>
-<p>
-    To be written
-</p>
+
+> We now have everything we need to run the app locally. By using docker compose, we set up two running containers, one for the UI, and the other for the API. You can now use the app just as if you were to us it on the internet. The API uses SAM Local and mounted volumes so if you make changes to the API code it will be reflected in real time. The UI uses Angular, Webpack and mounted volumes, so if you make changes to the UI code it will be reflected in real time on the browser.
+
 </details>
diff --git a/docs/setup.md → docs/setting-up-preliminary-tools.md b/docs/setup.md → docs/setting-up-preliminary-tools.md
diff --git a/docs/setting-up-remote.md b/docs/setting-up-remote.md
@@ -12,7 +12,7 @@ This guide is for you to have a working version of Cheet Sheet deployed to the i
 
 <details><summary>What just happened?</summary>
 
-> The first thing we need to do is provision infrastructure for the app. This includes things like S3 Buckets, Cognito Userpools and lambda roles. We do this through docker compose. The file called infrastructure.env, is what properly configures how to build the infrastructure. You could build the `infrastructure.env` file manually by following the [infrastructure.template.env](/.env_templates/infrastructure.template.env). The utility cli provides guided prompts to make it a bit easier. *If you want to learn more about what each configuration is, read the ENVIRONMENT variable glossary.*
+> The first thing we need to do is provision infrastructure for the app. This includes things like S3 Buckets, Cognito Userpools and lambda roles. We do this through docker compose. The file called infrastructure.env, is what properly configures how to build the infrastructure. You could also build the `infrastructure.env` file manually by following the [infrastructure.template.env](/.env_templates/infrastructure.template.env). It's just that the utility cli provides guided prompts to make it a bit easier. *If you want to learn more about what each configuration is, read the ENVIRONMENT variable glossary.*
 
 </details>
 
@@ -48,7 +48,7 @@ This guide is for you to have a working version of Cheet Sheet deployed to the i
 
 <details><summary>What just happened?</summary>
 
-> Now that we have infrastructure that can house our app we need to build and deploy the source code. The file called remote.env, is what properly configures how to and where to deploy things. You could build the `remote.env` file manually by following the [remote.template.env](/.env_templates/remote.template.env). The utility cli provides guided prompts to make it a bit easier. *If you want to learn more about what each configuration is, read the ENVIRONMENT variable glossary.*
+> Now that we have infrastructure that can house our app we need to build and deploy the source code. The file called remote.env, is what properly configures how to and where to deploy things. You could also build the `remote.env` file manually by following the [remote.template.env](/.env_templates/remote.template.env). It's just that the utility cli provides guided prompts to make it a bit easier. *If you want to learn more about what each configuration is, read the ENVIRONMENT variable glossary.*
 
 </details>