diff --git a/.env_templates/infrastructure.template.env b/.env_templates/infrastructure.template.env index 8ae2afb..61dcafb 100644 --- a/.env_templates/infrastructure.template.env +++ b/.env_templates/infrastructure.template.env @@ -3,10 +3,12 @@ # run this app locally, not host it to the public. ENVIRONMENT= +# AWS credentials and region AWS_DEFAULT_REGION= AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= +# Route53 Configurations AWS_ROUTE53_HOSTED_ZONE_ID= SITE_SUB_DOMAIN= SITE_DOMAIN= diff --git a/.env_templates/local.template.env b/.env_templates/local.template.env index 3fb5530..41a84cd 100644 --- a/.env_templates/local.template.env +++ b/.env_templates/local.template.env @@ -6,17 +6,17 @@ ENVIRONMENT=local CLIENT_UI_URL=http://localhost:4200 API_URL=http://localhost:3000 -# AWS Credentials and regions +# AWS credentials and region AWS_DEFAULT_REGION= AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= -# AWS Cognito configurations +# Cognito configurations COGNITO_CLIENT_ID= COGNITO_AUTH_URL= COGNITO_JWKS_BASE64= -# Bucket where application data is saved +# Folder path where application data is saved SHEET_DATA_S3_BUCKET= # AWS Layer ARN, with necessary dependencies for the Python3.7 API @@ -27,5 +27,5 @@ LAMBDA_LAYER= # Tell SAM Local the Path of the API, so it can properly mount volumes SAM_LOCAL_ABSOLUTE_PATH= -# Comment this out if your okay with SAM sending data +# Comment this out if you are okay with SAM sending data SAM_CLI_TELEMETRY=0 diff --git a/.env_templates/remote.template.env b/.env_templates/remote.template.env index f4248be..b261f66 100644 --- a/.env_templates/remote.template.env +++ b/.env_templates/remote.template.env @@ -2,28 +2,31 @@ # This should match the environment of infrastructure it is going to # be deployed to. ENVIRONMENT= -SITE_SUB_DOMAIN= + +# Should be the same as infrastructure.env +SITE_SUB_DOMAIN SITE_DOMAIN= # The Base url for the Frontend and Backend CLIENT_UI_URL= API_URL= -# AWS Credentials and regions +# AWS credentials and region AWS_DEFAULT_REGION= AWS_ACCESS_KEY_ID= AWS_SECRET_ACCESS_KEY= -# Cognito +# Cognito configurations COGNITO_CLIENT_ID= COGNITO_AUTH_URL= COGNITO_JWKS_BASE64= -# Where application data is saved +# Folder path where application data is saved SHEET_DATA_S3_BUCKET= # AWS IAM Role ARN for Lambda function. The minimum requirement is for: # - Read and Write Access to the Sheet Data S3 Bucket +# - Write logs to Cloud Watch # - The ability to invoke itself LAMBDA_IAM_ROLE= @@ -35,5 +38,5 @@ LAMBDA_LAYER= # Bucket that facilatates SAM deployments of the Api API_DEPLOYMENT_S3_BUCKET= -# Comment this out if your okay with SAM sending data +# Comment this out if you are okay with SAM sending data SAM_CLI_TELEMETRY=0 diff --git a/.utils/create-env.js b/.utils/create-env.js index 680fd6e..cfecfee 100644 --- a/.utils/create-env.js +++ b/.utils/create-env.js @@ -7,13 +7,14 @@ const util = require('util'); var request = require('request-promise-native'); var AWS = require('aws-sdk'); -// Template for the infrastructure.env file generated +// Template for the remote.env file generated const generateRemoteEnvString = (params) => { return `` + `# What unique environment is this code will be deployed to. # This should match the environment of infrastructure it is going to # be deployed to. ENVIRONMENT=${params.ENVIRONMENT || ''} + SITE_SUB_DOMAIN=${params.SITE_SUB_DOMAIN || ''} SITE_DOMAIN=${params.SITE_DOMAIN || ''} @@ -21,21 +22,22 @@ SITE_DOMAIN=${params.SITE_DOMAIN || ''} CLIENT_UI_URL=${params.CLIENT_UI_URL || ''} API_URL=${params.API_URL || ''} -# AWS Credentials and regions +# AWS credentials and region AWS_DEFAULT_REGION=${params.AWS_DEFAULT_REGION || ''} AWS_ACCESS_KEY_ID=${params.AWS_ACCESS_KEY_ID || ''} AWS_SECRET_ACCESS_KEY=${params.AWS_SECRET_ACCESS_KEY || ''} -# Cognito +# Cognito configurations COGNITO_CLIENT_ID=${params.COGNITO_CLIENT_ID || ''} COGNITO_AUTH_URL=${params.COGNITO_AUTH_URL || ''} COGNITO_JWKS_BASE64=${params.COGNITO_JWKS_BASE64 || ''} -# Where application data is saved +# Folder path where application data is saved SHEET_DATA_S3_BUCKET=${params.SHEET_DATA_S3_BUCKET || ''} # AWS IAM Role ARN for Lambda function. The minimum requirement is for: # - Read and Write Access to the Sheet Data S3 Bucket +# - Write logs to Cloud Watch # - The ability to invoke itself LAMBDA_IAM_ROLE=${params.LAMBDA_IAM_ROLE || ''} @@ -44,13 +46,14 @@ LAMBDA_IAM_ROLE=${params.LAMBDA_IAM_ROLE || ''} # - cryptography==2.8 LAMBDA_LAYER=${params.LAMBDA_LAYER || ''} -# SHEET_DATA_S3_BUCKET: S3 bucket that stores all sheets +# Bucket that facilatates SAM deployments of the Api API_DEPLOYMENT_S3_BUCKET=${params.API_DEPLOYMENT_S3_BUCKET || ''} -# Comment this out if your okay with SAM sending data +# Comment this out if you are okay with SAM sending data SAM_CLI_TELEMETRY=0 `} +// Template for the local.env file generated const generateLocalEnvString = (params) => { return `` + `# This env file does not deploy anything. It is only used for local @@ -61,12 +64,12 @@ ENVIRONMENT=${params.ENVIRONMENT || ''} CLIENT_UI_URL=${params.CLIENT_UI_URL || ''} API_URL=${params.API_URL || ''} -# AWS Credentials and regions +# AWS credentials and region AWS_DEFAULT_REGION=${params.AWS_DEFAULT_REGION || ''} AWS_ACCESS_KEY_ID=${params.AWS_ACCESS_KEY_ID || ''} AWS_SECRET_ACCESS_KEY=${params.AWS_SECRET_ACCESS_KEY || ''} -# AWS Cognito configurations +# Cognito configurations COGNITO_CLIENT_ID=${params.COGNITO_CLIENT_ID || ''} COGNITO_AUTH_URL=${params.COGNITO_AUTH_URL || ''} COGNITO_JWKS_BASE64=${params.COGNITO_JWKS_BASE64 || ''} @@ -82,30 +85,11 @@ LAMBDA_LAYER=${params.LAMBDA_LAYER || ''} # Tell SAM Local the Path of the API, so it can properly mount volumes SAM_LOCAL_ABSOLUTE_PATH=${params.SAM_LOCAL_ABSOLUTE_PATH || ''} -# Comment this out if your okay with SAM sending data +# Comment this out if you are okay with SAM sending data SAM_CLI_TELEMETRY=0 ` } - - -const createEnv = (environment) => { - if(environment === 'local') { - var params = { - }; - dotenv.config({path: '../infrastructure.env'}); - AWS.config.region = 'us-east-1' - AWS.config.credentials = new AWS.Credentials(process.env.AWS_ACCESS_KEY_ID, process.env.AWS_SECRET_ACCESS_KEY); - const cloudformation = new AWS.CloudFormation({ - apiVersion: '2010-05-15' - }); - cloudformation.listExports(params, function(err, data) { - if (err) console.log(err, err.stack); // an error occurred - else console.log(data); // successful response - }); - } -} - /** * These are the question propmts for this CLI command */ @@ -123,12 +107,7 @@ const questions = [ ]; - -// const describeStacksPromise = util.promisify(cloudformation.describeStacks); - -// - Get Stack outputs - - +// Turn file writer into a promise const writeFilePromise = util.promisify(fs.writeFile); // Export CLI Command @@ -178,9 +157,6 @@ module.exports = () => { AWS.config.credentials = new AWS.Credentials(answers.AWS_ACCESS_KEY_ID, answers.AWS_SECRET_ACCESS_KEY); const cloudformation = new AWS.CloudFormation({ apiVersion: '2010-05-15' }); - - - // Read exports from CloudFormation return cloudformation.describeStacks({ StackName: infrastructureStackName }).promise() .then((data) => { diff --git a/.utils/create-infra-env.js b/.utils/create-infra-env.js index 5f1846a..61dbd5a 100644 --- a/.utils/create-infra-env.js +++ b/.utils/create-infra-env.js @@ -15,11 +15,12 @@ return `` + # run this app locally, not host it to the public. ENVIRONMENT=${params.ENVIRONMENT || ''} -# AWS Creds +# AWS credentials and region AWS_DEFAULT_REGION=${params.AWS_DEFAULT_REGION || ''} AWS_ACCESS_KEY_ID=${params.AWS_ACCESS_KEY_ID || ''} AWS_SECRET_ACCESS_KEY=${params.AWS_SECRET_ACCESS_KEY || ''} +# Route53 Configurations AWS_ROUTE53_HOSTED_ZONE_ID=${params.AWS_ROUTE53_HOSTED_ZONE_ID || ''} SITE_SUB_DOMAIN=${params.SITE_SUB_DOMAIN || ''} SITE_DOMAIN=${params.SITE_DOMAIN || ''} diff --git a/README.md b/README.md index 79d50b1..a7a3900 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ Cheet Sheet is an open source Content Management System for developers and development teams to Create, Edit and Share code snippets. This accelerates software engineering by having a centralized place where one can see how they or teammates have solved common problems in the past.

-Setting up Cheet Sheet for you or your organization is simple. All you need is Docker, node and an AWS account. It's 100% Serverless so your costs and infrastructure will automatically grow and shrink based on your needs with minimal effort on your part. ***Read [Getting Started](/docs/getting-started.md)*** +Setting up Cheet Sheet for you or your organization is simple. All you need is Docker, Node and an AWS account. It's 100% Serverless so your costs and infrastructure will automatically grow and shrink based on your needs with minimal effort on your part. ***Read [Getting Started](/docs/getting-started.md)***

Here is my own instance of the application: https://cheet-sheet.gugz.net/

@@ -25,7 +25,7 @@ If you use the app and like it please leave a star. If you find bugs feel free t width="700" />

-Cheet Sheet is fairly simple to understand. Code snippets are are organized as sheets with self defined category (ex: Programming Language, Framework, tool, etc). Each sheet has two columns of index cards. Every index card has a code snippet. You can copy the entire content of the card by clicking on the copy icon. Everything here is read only. +Cheet Sheet is fairly simple to understand. Code snippets are are organized as sheets with a self defined category (ex: Programming Language, Framework, tool, etc). Each sheet has two columns of index cards. Every index card has a code snippet. You can copy the entire content of the card by clicking on the copy icon. Everything here is read only.

Personal View

@@ -57,9 +57,9 @@ You can enter Edit mode by manually toggling it on and off. When on, you can add />

-Team workspaces are also available for logged in users. Everything you can do on a Personal workspace applies here except that this workspace can be viewed and edited by anyone who is on your team. To create a new workspace all you need to do is simply make a group in the Cognito user pool and add users to it. The name of the group is the name of team. +Team workspaces are also available for logged in users. Everything you can do on a Personal workspace applies here, except that this workspace can be viewed and edited by anyone who is on your team. To create a new Team workspace all you need to do is make a group in the Cognito user pool and add users to it. The name of the group is the name of team.

-The sheets and index cards that are viewable by the public, are part of the Public Workspace. For a user to modify the sheets in this workspace they must be added to the `admin` user group in cognito. +The sheets and index cards that are viewable by the public, are a part of the Public workspace. For a user to modify the sheets in this workspace they must be added to the `admin` user group in Cognito.

Built With

Here are some of the publicly available tools Cheet Sheet was built with: diff --git a/api/src/__core__/authentication_middleware.py b/api/src/__core__/authentication_middleware.py index b1b7039..248751e 100644 --- a/api/src/__core__/authentication_middleware.py +++ b/api/src/__core__/authentication_middleware.py @@ -12,18 +12,16 @@ from jwt.algorithms import RSAAlgorithm def apply(event): - """ - """ headers = event['headers'] if ('Authorization' in headers) and (headers['Authorization']): try: - # Parse Web Keys and Headers of Access and Id JWT tokens + # Parse Web Keys and Headers of Access JWT tokens web_keys = { token['kid']: token for token in decode_base64_to_json(COGNITO_JWKS_BASE64)['keys'] } access_token = headers['Authorization'].replace('Bearer ', '') access_token_header = jwt.get_unverified_header(access_token) - # Verify Access and Id Token + # Verify Access Token public_access_key = RSAAlgorithm.from_jwk(json.dumps(web_keys[access_token_header['kid']])) decoded_access_token = jwt.decode(access_token, public_access_key, algorithms='RS256', verify=True) diff --git a/docker-compose.deploy.code.yml b/docker-compose.deploy.code.yml index 55e33de..976dbb4 100644 --- a/docker-compose.deploy.code.yml +++ b/docker-compose.deploy.code.yml @@ -1,20 +1,12 @@ # ------------------------------------------------------------------------------ # CODE DOCKER COMPOSE # -# This Docker Compose is meant to deploy frontend code and backend code -# to a remote environment. -# -# What this deploys: -# - Angular code to an S3 bucket -# - Lambda Function that connects to an API Gateway +# This Docker Compose is meant to deploy/update frontend code and backend code +# to a remote environment. With this we create the Code Cloud Formation stack. # # Prerequisites: -# - Cognito Userpool -# - API Gateway -# - S3 Bucket for UI hosting -# - S3 Bucket for App Data Storage -# - IAM Role for a Lambda Function -# Should have permission to update the App Data Storage bucket +# - Infrastructure Stack +# - Lambda Layer with pyjwt==1.7.1 & cryptography==2.8 # # ------------------------------------------------------------------------------ # # Temporarily set to version 3.2 to support circle CI diff --git a/docker-compose.deploy.infrastructure.yml b/docker-compose.deploy.infrastructure.yml index 975e273..058448e 100644 --- a/docker-compose.deploy.infrastructure.yml +++ b/docker-compose.deploy.infrastructure.yml @@ -1,19 +1,16 @@ # ------------------------------------------------------------------------------ # INFRASTRUCTURE DOCKER COMPOSE # -# This Docker Compose is meant provision the necessary AWS resources -# for a user. This includes VPC's, Subnets, Roles and Policies. +# This Docker Compose can deploy the Infrastructure Stack and the Networking Stack # -# What this sets up: -# - Cognito Userpool -# - S3 Bucket for UI hosting -# - S3 Bucket for App Data Storage -# - S3 Bucket for Code Deployment Artifacts +# Infrastructure Stack Prerequisites: +# - None, this is the first stack deployed +# +# Networking Stack Prerequisites: +# - Infrastructure Stack +# - ACM Certifcate +# - Route53 Domain # -# Prerequisites: -# - AWS VPC -# - Route53 Domains -# - AWS Certificate Manager # ------------------------------------------------------------------------------ version: '3.7' services: diff --git a/docs/architecture-overview.md b/docs/architecture-overview.md index 48c63dc..7020bc0 100644 --- a/docs/architecture-overview.md +++ b/docs/architecture-overview.md @@ -9,13 +9,13 @@ />


-When the user visits our web page, the frontend loads from an S3 bucket that saves all of our published Angular Code. Once on the website, REST requests get send to Api Gate way which asks a Lambda function to handle it. Lambda then queries our Sheet Data S3 bucket to read and change our application's state (this is where all our sheets and index cards are saved). We are able to support package dependencies through a Lambda Layer. +When the user visits our web page, the frontend loads from an S3 bucket that saves all of our published Angular Code. When the website get's used, REST requests get send to Api Gateway which asks a Lambda function to handle it. Lambda then queries our Sheet Data S3 bucket to read and change our application's state (this is where all our sheets and index cards are saved). We are able to support package dependencies through a Lambda Layer.

-Our api uses a monolithic function, this means all requests are handled by the same function. +Our Api uses a monolithic function, this means all requests are handled by the same function.

Authentication is handled by Cognito. When the user is a verified, a secure JWT token is received and saved in the browser. Then when making authenticated requests to the api, lambda makes sure that the token is properly signed and encrypted. This is what prevents a user from accessing and editing Workspaces they don't belong to.

-The Api Deployment does not play an active role in the Infrastructure. But, it is something that is needed when we want to make updates to our API logic. +The Api Deployment bucket does not play an active role in the Infrastructure. But, it is something that is needed when we want to make updates to our API logic. ### Deployment Process

@@ -78,7 +78,7 @@ Other things to note: />

-This repo also supports local development. This is so we can develop and test new features on our own machine before deploying it. To do this the Api and the UI are dockerized. Both services use mounted volumes so code changes can be reflected in real time. +This repo also supports local development. This is so we can develop and test new features on our own machine before deploying them. To do this the Api and the UI are dockerized. Both services use mounted volumes so code changes can be reflected in real time. The Api Service uses SAM local. Anytime a request is sent to the Api, SAM will run a temporary Docker container to simulate the Lambda function. diff --git a/docs/environment-variable-glossary.md b/docs/environment-variable-glossary.md index 71b7853..cc08d5b 100644 --- a/docs/environment-variable-glossary.md +++ b/docs/environment-variable-glossary.md @@ -12,20 +12,20 @@ This README tries to break down what each of these variables are. | --------------------------------- | ------------------------------------------------------------------------- | | ENVIRONMENT | This describes what unique environment is this app for. For example, prod, staging, dev, etc. This should be alphabetical and have no spaces. If set to "local", this will configure the app specifically for running on your machine and not for deploying it to AWS. | | AWS_DEFAULT_REGION | This is AWS region you want to deploy the app to. Ex: us-east-1, us-west-2, etc. | -| AWS_ACCESS_KEY_ID | This is for the IAM Credentials with which we gain the authentication provision infrastructure and deploy the app to AWS with. You need this for local development too, because some resources like S3 will sill run in the cloud. | -| AWS_SECRET_ACCESS_KEY | This is another IAM Credential (pairs with AWS_ACCESS_KEY_ID) with which we gain the authentication provision infrastructure and deploy the app to AWS with. You need this for local development too, because some resources like S3 will sill run in the cloud. | -| SITE_SUB_DOMAIN | This is the subdomain to which your app will be deployed to. For example, if you wish to have the app on https://cheet-sheet.mydomain.com this variable is set to `cheet-sheet`. For local environments this is not used for networking. Only for Naming conventions for S3 resources. | -| SITE_DOMAIN | This is the subdomain to which your app will be deployed to. For example, if you wish to have the app on https://cheet-sheet.mydomain.com this variable is set to `mydomain.com`. You must own this domain on Route53 if you are deploying the app to the internet. For local environments this is not used for networking. Only for Naming conventions for S3 resources. | +| AWS_ACCESS_KEY_ID | This is for the IAM Credentials with which we gain access to AWS with. You need this for local development too, because some resources like S3 will sill run in the cloud. | +| AWS_SECRET_ACCESS_KEY | This is another IAM Credential (pairs with AWS_ACCESS_KEY_ID) with which we gain access to AWS with. You need this for local development too, because some resources like S3 will sill run in the cloud. | +| SITE_SUB_DOMAIN | This is the subdomain to which your app will be deployed to. For example, if you wish to have the app on https://cheet-sheet.mydomain.com this variable is set to `cheet-sheet`. For local environments this is not used for networking, but still used for naming conventions of S3 resources. | +| SITE_DOMAIN | This is the subdomain to which your app will be deployed to. For example, if you wish to have the app on https://cheet-sheet.mydomain.com this variable is set to `mydomain.com`. You must own this domain on Route53 if you are deploying the app to the internet. For local environments this is not used for networking, but still used for naming conventions of S3 resources. | | AWS_ACM_CERTIFICATE_ARN | Not need for `ENVIRONMENT=local`. This is the AWS ACM ARN for the SSL certificate of the website, so we can use https. The certificate must valid for both these domains: `{SITE_SUB_DOMAIN}`.`{SITE_DOMAIN}`, `{SITE_SUB_DOMAIN}`.api.`{SITE_DOMAIN}` | | AWS_ROUTE53_HOSTED_ZONE_ID | This is the Zone Id for `SITE_DOMAIN` | | CLIENT_UI_URL | https://`{SITE_SUB_DOMAIN}`.`{SITE_DOMAIN}` if `ENVIRONMENT!=local`, `http://localhost:4200` if `ENVIRONMENT=local`| | API_URL | https://`{SITE_SUB_DOMAIN}`.api.`{SITE_DOMAIN}` if `ENVIRONMENT!=local`, `http://localhost:3000` if `ENVIRONMENT=local`| -| COGNITO_CLIENT_ID | This is the Id of the Cognito User Pool Client. We provision a different user pool for every different Environment. You can find this on your Infrastructure stack Outputs after it is deployed. | -| COGNITO_AUTH_URL | This is the Cognito Domain, that handles our authentication and hosts the login page. You can find this on your Infrastructure stack Outputs after it is deployed.| -| COGNITO_JWKS_BASE64 | In order to verify web tokens on the backend for login users we need a public. AWS hosts these keys as a Json Web Key Set on https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json. You can find the User Pool Id on your Infrastructure stack Outputs after it is deployed. | +| COGNITO_CLIENT_ID | This is the Id of the Cognito User Pool Client. We provision a different user pool for every different Environment. You can find this on your Infrastructure stack's Outputs after it is deployed. | +| COGNITO_AUTH_URL | This is the Cognito Domain, that handles our authentication and hosts the login page. You can find this on your Infrastructure stack's Outputs after it is deployed.| +| COGNITO_JWKS_BASE64 | In order to verify web tokens on the backend for login users we need a public key. AWS hosts these keys as a Json Web Key Set on https://cognito-idp.{region}.amazonaws.com/{userPoolId}/.well-known/jwks.json. You can find the User Pool Id on your Infrastructure stack's Outputs after it is deployed. | | SHEET_DATA_S3_BUCKET | This is the S3 bucket name where the different sheets and index cards are saved. You can find this on your Infrastructure stack Outputs after it is deployed. | -| LAMBDA_IAM_ROLE | This is the IAM role that gives the Lambda function that's behind our api, the necessary permissions to communicate with other AWS resources. You can find this on your Infrastructure stack Outputs after it is deployed. | -| LAMBDA_LAYER | AWS ARN for the Layer. AWS Lambda Layers are for you to save dependencies for the Lambda function that's behind our api. By default Lambda comes with several libraries out of the box, but we still need 2 more. They are pyjwt==1.7.1 and cryptography==2.8. You will need to make one yourself you don't have on. You can look at https://github.com/gugzkumar/my-python-lambda-layers for guidance. | -| API_DEPLOYMENT_S3_BUCKET | This is the S3 bucket name that SAM leverages to deploy the backend code of our app. You can find this on your Infrastructure stack Outputs after it is deployed. | -| SAM_LOCAL_ABSOLUTE_PATH | Absolute path of the `api` folder on your machine. In order for local development to work SAM needs to know where it is located. | +| LAMBDA_IAM_ROLE | This is the IAM role that gives the Lambda function behind our api, the necessary permissions to communicate with other AWS resources. You can find this on your Infrastructure stack's Outputs after it is deployed. | +| LAMBDA_LAYER | AWS ARN for the Layer. AWS Lambda Layers are for you to provide dependencies for the Lambda function behind our api. Lambda comes with several libraries out of the box, but we still need 2 more. They are pyjwt==1.7.1 and cryptography==2.8. You will need to make one yourself if you don't have one. You can look at https://github.com/gugzkumar/my-python-lambda-layers for guidance. | +| API_DEPLOYMENT_S3_BUCKET | This is the S3 bucket name that SAM leverages to deploy the backend code of our app. You can find this on your Infrastructure stack's Outputs after it is deployed. | +| SAM_LOCAL_ABSOLUTE_PATH | Absolute path of the `api` folder on your machine. In order for local development to work, SAM needs to know where it is located. | | SAM_CLI_TELEMETRY | Set this to 0 if you don't want to send AWS logistics about your use of SAM. Set to 1 if you're okay with it. This can help AWS make improvements to SAM. | diff --git a/docs/getting-started.md b/docs/getting-started.md index 295f183..902cf05 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -3,7 +3,7 @@ This document and the following ones will help you set up Cheet Sheet. ### Preliminary Setup -Click [here](/docs/setting-up-preliminary-tools.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/or deploy it to AWS. ### Set Up and Run Locally 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. diff --git a/docs/setting-up-ci-cd.md b/docs/setting-up-ci-cd.md index 9321edd..3a5145a 100644 --- a/docs/setting-up-ci-cd.md +++ b/docs/setting-up-ci-cd.md @@ -1,6 +1,6 @@ # Setting Up Continuous Deployment Via CircleCI -Continuous Deployment automates the updating of new code in our Api and UI so that we can focus on building features rather than how t launch them. CircleCI is easy to use, has a free tier, and takes away the hassle of have to set up infrastructure for it. +Continuous Deployment automates the updating of new code in our Api and UI so that we can focus on building features rather than worrying about how to launch them. CircleCI is easy to use, has a free tier, and takes away the hassle of have to set up infrastructure for it. ## STEP 1: Connect CircleCI to your repo @@ -9,9 +9,10 @@ Continuous Deployment automates the updating of new code in our Api and UI so th ## STEP 2: Create the ENVIRONMENT variable out of your remote.env -1. In [Setting Up And Launching The App On AWS](/docs/setting-up-remote.md) you create an `remote.env` file for code deploys -1. From the .utils folder run `node main.js create-infra-env` generate-base64-env. This will encode all contents of the `.env` file as base64 and spit it out. -1. The way we do continuous deployment is by mapping a branch in your repo to environment variable that has the contents of `remote.env` (base 64 encoded). Outbox the following deployment strategies are provided. If you want change the branch name, environment variable name, or add a new strategy follow **STEP 3**. +1. In [Setting Up And Launching The App On AWS](/docs/setting-up-remote.md) find the `remote.env` file you made for code deploys +1. From the `.utils` folder run `node main.js create-infra-env` generate-base64-env. This will encode all contents of the `.env` file as base64 and spit it out. +1. The way we do continuous deployment is by mapping a branch in your repo to an environment variable that has the contents of `remote.env` (base 64 encoded). Out of the box, the following deployment strategies are provided. If you want to change the branch name, environment variable name, or add a new strategy, follow **STEP 3**. + | Branch | CircleCI Environment Variable | | ------ | ----------------------------- | | master | PROD_ENV_FILE | @@ -21,7 +22,7 @@ Continuous Deployment automates the updating of new code in our Api and UI so th 1. Copy the output of the cli command, and set it as the desired Environment Variable. -## STEP 3: Update .circleci/config.yml if needed (Optional) +## STEP 3: Update `.circleci/config.yml` if needed (Optional) If you want to add more environments than supported out of the the box, modify the `load-env` command: @@ -47,5 +48,3 @@ load-env: exit 1 fi ``` - -# diff --git a/docs/setting-up-locally.md b/docs/setting-up-locally.md index 6d6e89d..c9b6989 100644 --- a/docs/setting-up-locally.md +++ b/docs/setting-up-locally.md @@ -1,18 +1,18 @@ # 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. +This guide is for you to have a working version of Cheet Sheet running on your computer. 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 project folder. ## STEP 1: Create Your infrastructure.env File -**Warning: if you've already made infrastructure.env before, it will be overridden. So save it if you don't want to lose it** +**Warning: if you've already made an infrastructure.env before, it will be overridden. So save it if you don't want to lose it** -1. From the .utils folder run `node main.js create-infra-env` +1. From the `.utils` folder run `node main.js create-infra-env` 2. Follow the guided prompt to create `infrastructure.env` 3. Confirm you now have a file in your root folder called `infrastructure.env`
What just happened? -> 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.* +> The first thing we need to do is provision infrastructure for the app. This includes things like S3 Buckets and 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.*
@@ -34,18 +34,18 @@ This guide is for you to have a working version of Cheet Sheet deployed to your > 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. +> **Note:** Because this is only meant to run locally on our machine, the 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. ## STEP 3: Create Your .env File -1. From the .utils folder run `node main.js create-infra-env` +1. From the `.utils` folder run `node main.js create-env` 1. Follow the guided prompt to create `.env` from `infrastructure.env` 1. Confirm you now have a file in your root folder called `.env`
What just happened? -> 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.* +> Now that we have a Cognito Userpool and an S3 bucket created from the previous step, we 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.*
@@ -55,11 +55,11 @@ This guide is for you to have a working version of Cheet Sheet deployed to your 1. Run `docker-compose up --build -d` 1. Wait for a minute or two after the command finishes running 1. You can now see the site on http://localhost:4200 :beers: -1. Code changes you now make to the api and ui should happen real time to the app now +1. Code changes you now make to the api and ui should happen real time 1. Run `docker-compose down -v` to take down the app
What just happened? -> 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 use 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. +> 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 use 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.
diff --git a/docs/setting-up-preliminary-tools.md b/docs/setting-up-preliminary-tools.md index 06ce68e..4467515 100644 --- a/docs/setting-up-preliminary-tools.md +++ b/docs/setting-up-preliminary-tools.md @@ -1,12 +1,12 @@ # Preliminary Setup and Preparation -This is all the preliminary things you will need to do before running the app on your computer or deploying it to AWS. +These are all the preliminary things you will need to do before running the app on your computer or deploying it to AWS. ## Repo -First fork or clone this repo on your own Github account. I strongly suggest you use Github since it will be easy to automate code deployments through Circle CI. +First fork or clone this repo on your own Github account. I strongly suggest you use Github since it will be easy to automate code deployments through CircleCI. ## Docker -Install Docker for Desktop and Docker Compose for your machine: +Install Docker and Docker Compose for your computer: - https://www.docker.com/ ## AWS @@ -20,7 +20,7 @@ You will need to have an AWS IAM account, with permissions to the following serv - Cloudwatch - Cloudfront - Route53 -- IAM *create roles and policies for lambda* +- IAM *to create roles and policies for lambda* Next you will need to have or create the following resources: @@ -57,6 +57,6 @@ Set up an SSL Certificate throw through AWS' Certificate Manager. You will want ## Setup Utility CLI -To streamline the creation of configuration variables and files we have some cli tools built with Node JS. Download Node if you do not have it. Then from the the `.utils` folder run `npm install` to install the cli. Run `node main.js --help` to confirm the utility cli works. +To streamline the creation of configuration variables and files I've made some cli tools built with Node JS. Download Node if you do not have it. Then from the the `.utils` folder run `npm install` to install the cli. Run `node main.js --help` to confirm the utility cli works.

https://nodejs.org/en/ diff --git a/docs/setting-up-remote.md b/docs/setting-up-remote.md index 1f04890..98f2bf9 100644 --- a/docs/setting-up-remote.md +++ b/docs/setting-up-remote.md @@ -1,18 +1,18 @@ # Setting Up And Launching The App On AWS -This guide is for you to have a working version of Cheet Sheet deployed to the internet for you or your team to access from anywhere. All commands, unless otherwise noted, should be ran from the root of the project folder. +This guide is for you to have a working version of Cheet Sheet deployed to the internet for you or your team to access from anywhere. All commands, unless otherwise noted, should be ran from the root project folder. ## STEP 1: Create Your infrastructure.env File -**Warning: if you've already made infrastructure.env before, it will be overridden. So save it if you don't want to lose it.** +**Warning: if you've already made an infrastructure.env before, it will be overridden. So save it if you don't want to lose it.** -1. From the .utils folder run `node main.js create-infra-env` +1. From the `.utils` folder run `node main.js create-infra-env` 2. Follow the guided prompt to create `infrastructure.env` 3. Confirm you now have a file in your root folder called `infrastructure.env`
What just happened? -> 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.* +> 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.*
@@ -40,9 +40,9 @@ This guide is for you to have a working version of Cheet Sheet deployed to the i ## STEP 3: Create Your remote.env File -**Warning: if you've already made remote.env before, it will be overridden. So save it if you don't want to lose it.** +**Warning: if you've already made an remote.env before, it will be overridden. So save it if you don't want to lose it.** -1. From the .utils folder run `node main.js create-infra-env` +1. From the .utils folder run `node main.js create-env` 1. Follow the guided prompt to create `remote.env` from `infrastructure.env` 1. Confirm you now have a file in your root folder called `remote.env` @@ -54,10 +54,10 @@ This guide is for you to have a working version of Cheet Sheet deployed to the i ## STEP 4: Build and Deploy The Code -**Note: SITE_DOMAIN and SITE_SUB_DOMAIN are what is defined in infrastructure.env** +**Note: ENVIRONMENT, SITE_DOMAIN and SITE_SUB_DOMAIN are what is defined in infrastructure.env** 1. Run `docker-compose -f docker-compose.deploy.code.yml run --rm serverless-lambda-api sh deploy.sh` -1. The command above deploys your code for the API +1. The command above deploys your code for the Api 1. Once it ran confirm in AWS Cloudformation you have a new stack called `CheetSheetCodeStack-{ENVIRONMENT}` with the status `CREATE_COMPLETE` 1. Run `docker-compose -f docker-compose.deploy.code.yml run --rm serverless-angular-client-ui sh -c "node build-env.js && npm run build-prod"` 1. You should now see a folder called `client-ui/angular-output`. In here is every thing you need for your front end to work. @@ -65,11 +65,11 @@ This guide is for you to have a working version of Cheet Sheet deployed to the i
What just happened? -> The first thing that happens is the deploy of the API. We run a docker container built with the AWS SAM cli, a configuration template for the REST API, and source code of the Lambda Function. This will produce a separate Cloudformation stack for Code. +> The first thing that happens is the deploy of the Api. We run a docker container built with the AWS SAM cli, a configuration template for the REST Api, and source code of the Lambda Function. This will produce a separate Cloudformation stack for Code. > > The second thing that happens is the deploy of the UI source code. We run a docker container built with the Angular that outputs static files for the frontend. Then copy and paste it into our UI bucket which will be the source of truth for our frontend. > -> Again docker is meant to reduce the number of things you have to install. It also makes easy to plug in to CircleCI for Continuous Deployment. +> Again docker is meant to reduce the number of things you have to install. It also makes it easy to plug in to CircleCI for Continuous Deployment.