aws-samples/lambda-refarch-webapp

The Web Application reference architecture is a general-purpose, event-driven, web application back-end that uses AWS Lambda, Amazon API Gateway for its business logic. It also uses Amazon DynamoDB as its database and Amazon Cognito for user management. All static content is hosted using AWS Amplify Console.

Serverless Reference Architecture: Web Application

README Languages: PT

Introduction

The Web Application reference architecture is a general-purpose, event-driven, web application back-end that uses AWS Lambda, Amazon API Gateway for its business logic. It also uses Amazon DynamoDB as its database and Amazon Cognito for user management. All static content is hosted using AWS Amplify Console.

This application implements a simple To Do app, in which a registered user can create, update, view the existing items, and eventually, delete them.

Architectural Diagram

Application Components

The Web Application is built from 3 different components.

Front End Application

The front-end application is all the static content (HTML files, CSS files, JavaScript files and images) that are generated by create-react-app. All these objects are hosted on AWS Amplify Console.

When a user connects to the web site, the needed resources are downloaded to their browser and start to run there. When the application needs to communicate with the backend it does so by issuing REST API calls to the backend.

Back End Application (Business Logic)

The backend application is where the actual business logic is implemented. The code is implemented using Lambda functions fronted by an API Gateway REST API. In our case, we have different Lambda functions, each handling a different aspect of the application: list the to-do items, get details about a specific item, update an item, create a new item, mark an item as complete and delete an existing item. The application saves all items in a DynamoDB table.

User Registration and Authentication

As the ToDo application contains personal information (the user's ToDo items), access is restricted only to registered and authenticated users. Each user can access only their own items.

To accomplish this, we are using Cognito User Pools, which allows users to register to the application, authenticate and so on. Only after a user is authenticated, the client will receive a JWT token which it should then use when making the REST API calls.

Running the Example

Fork this repository to your own GitHub account, as you will need to create a Personal Access Token in Github for the Amplify console, as well as provide your GitHub repository URL in the deployment.

You can use the provided AWS SAM template to launch a stack that shown here on this Serverless reference architecture. Details about the resources created by this template are provided in the SAM Template Resources section of this document.

Generating your Github Access Token

In order for use the Amplify Console, you need to generate a personal access token. Once created, an access token should be stored in a safe place, as it may not be available to be seen the next time and may need to regenerate a new one again. In order to setup your access token, go to New personal access page in GitHub.

Note that you might need to enter your password in order to proceed.

Using SAM and the Amplify Console to Build and Deploy the Full Stack Application

You can deploy the full stack application using the deployment script:

export AWS_DEFAULT_REGION=<your preferred region, i.e. us-east-1>
export STACK_NAME=<a unique name for your CloudFormation stack>
./deploy.sh

The script will use the SAM CLI to build your backend functions, and then the guided deployment feature of the SAM CLI for the initial backend deployment. You will be prompted for a set of parameters, and can accept the defaults for all parameters with the exception of the GitHub Repository URL and the GitHub OAuth token.

Building the Application Step by Step

Alternatively, you could run the build steps yourself in the CLI:

Build the backend functions

The AWS SAM CLI comes with abstractions for a number of Lambda runtimes to build your dependencies, and copies the source code into staging folders so that everything is ready to be packaged and deployed. The sam build command builds any dependencies that your application has, and copies your application source code to folders under aws-sam/build to be zipped and uploaded to Lambda.

sam build --use-container

Package the backend

Next, run sam package. This command takes your Lambda handler source code and any third-party dependencies, zips everything, and uploads the zip file to your Amazon S3 bucket. That bucket and file location are then noted in the packaged.yaml file. You use the generated packaged.yaml file to deploy the application in the next step.

sam package \
    --output-template-file packaged.yml \
    --s3-bucket $DEPLOYMENT_BUCKET

Deploy the backend

This command deploys your application to the AWS Cloud. It's important that this command explicitly includes both of the following:

• The AWS Region to deploy to. This Region must match the Region of the Amazon S3 source bucket.

• The CAPABILITY_IAM parameter, because creating new Lambda functions involves creating new IAM roles.

sam deploy \
    --template-file packaged.yml \
    --stack-name $STACK_NAME \
    --capabilities CAPABILITY_IAM

Testing locally (Optional)

To run lambda function , API Gateway and dynamodb locally follow the steps

To run the dynamodb table locally

docker run -p 8000:8000 amazon/dynamodb-local

Create a table in local Dynamodb environment

aws dynamodb create-table --table-name TodoTable --attribute-definitions AttributeName=id,AttributeType=S --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST --endpoint-url http://127.0.0.1:8000

Run the sam local module to test the application locally

sam local start-api --env-vars todo-src/test/environment/mac.json

Sample file of mac os is todo-src/test/environment/mac.json

Updating the Front-End Application

Once you deploy the infrastructure using SAM you will need to create a configuration file for your front-end web application. You can view the necessary values by describing your deployed stack:

aws cloudformation describe-stacks --stack-name $STACK_NAME --query "Stacks[0].Outputs[]"

Copy the default config file and update the values from the output above:

cp www/src/config.default.js www/src/config.js

You can run the front end locally for testing by setting the redirect_url value to https://localhost:8080 and running:

cd www/src
npm start

You can run the front end locally for testing and use the local api by setting the api_base_url value to http://127.0.0.1:8080

Deploy the frontend

Deploy your application by checking in your update to the config.js file and pushing that commit to your repo. Amplify Console will automatically deploy the update from there.

git add www/src/config.js
git commit -m 'Update frontend config'
git push

You can view the deployment process in the Amplify Console web console.

Cleaning Up the Example Resources

Delete the CloudFormation Stack

aws cloudformation delete-stack \
--stack-name $STACK_NAME

Delete the CloudWatch Log Groups

for log_group in $(aws logs describe-log-groups --log-group-name-prefix '/aws/lambda/'$STACK_NAME --query "logGroups[*].logGroupName" --output text); do
  echo "Removing log group ${log_group}..."
  aws logs delete-log-group --log-group-name ${log_group}
  echo
done

SAM Template Resources

Resources

The provided template creates the following resources:

• TodoUserPool - A Cognito UserPool that holds all the application users

• TodoUserPoolTokenClient - A Cognito UserPool Client used by the web application

• TodoDomain - The Cognito UserPool domain name

• TodoTable - The DynamoDB table used to hold all the ToDo items for all users

• TodoApi - The REST API that is used to expose the ToDo application functionality

• GetTodoFunction - The Lambda function used to retrieve a single ToDo item

• GetAllTodoFunction - The Lambda function used to retrieve all the ToDo items

• CompleteTodoFunction - The Lambda function used to set the state of an item to complete

• AddTodoFunction - The Lambda function used to create a new ToDo item

• UpdateTodoFunction - The Lambda function used to update the content of a ToDo item

• DeleteTodoFunction - The Lambda function used to delete a ToDo item

• ApiGatewayPushToCloudWatchRole - An IAM role that allows API Gateway to send log events to CloudWatch Logs

• ApiAccessLogGroup - The CloudWatch Logs Log Group used by API Gateway for its log messages

• AmplifyApp - Amplify Console application that will manage deployment of frontend updates based on pushes to GitHub

• AmplifyBranch - Connecting a GitHub branch to the Amplify Console application

• AmplifyRole - An IAM role that allows the Amplify Console to perform build and deployment actions

Notes

By default, the default Node.js HTTP/HTTPS agent creates a new TCP connection for every new request. To avoid the cost of establishing a new connection, you can reuse an existing connection.

For short-lived operations, such as DynamoDB queries, the latency overhead of setting up a TCP connection might be greater than the operation itself. Additionally, since DynamoDB encryption at rest is integrated with AWS KMS, you may experience latencies from the database having to re-establish new AWS KMS cache entries for each operation.

The easiest way to configure SDK for JavaScript to reuse TCP connections is to set the AWS_NODEJS_CONNECTION_REUSE_ENABLED environment variable to 1. This feature was added in the 2.463.0 release.

Read more about this feature on our Developer Guide.

Well-Architected Review

We have conducted a Well-Architected review for this application using the Serverless Application Lens. The results of this review can be found here.

License

This reference architecture sample is licensed under Apache 2.0.

lambda-refarch-webapp's Issues

Unable to Login - redirects back to login page

Reproduction Steps

Error Log

Environment

• **SAM CLI Version : 1.17.0
• **OS : Mac
• **Language : JS

Other

---

This is 🐛 Bug Report

AWS SAM Template - link does not exist

description of the bug: In the README.md of this repo, a link "AWS SAM Template" pointing to https://github.com/aws-samples/lambda-refarch-webapp/blob/master/template.yml results in 404 page.

Reproduction Steps

minimal amount of code that causes the bug (if possible) or a reference:
Click on the "AWS SAM Template" link on the README.md file

Error Log

what is the error message you are seeing?
404 Page not found

Environment

• SAM CLI Version :
• OS :
• Language :

Other

---

This is 🐛 Bug Report

Users aren't restricted to their own todo items

User A has access to User B's todos, and vice versa. There is no restriction of a todo list to the logged in user.

Reproduction Steps

1. Deploy the stack.
2. Go to the site.
3. Sign up as a user and enter a few todos.
4. Open another browser and sign up as a whole different user and view the todos.

Expected: The second user should only be able to see their todos and thus should have none.
Actual: The second user can see all of the first users todos.

Error Log

No error message.

Environment

• SAM CLI Version : 0.53.0
• OS :
• Language :

Other

The README.md states:
"As the ToDo application contains personal information (the user's ToDo items), access is restricted only to registered and authenticated users. Each user can access only their own items."

So I would expect a logged in user to only see their todos.

---

This is 🐛 Bug Report

Fix text and resolution on the diagram image

Just small stuff.
Anyway:
in the diagram image
Point 4:

Requests are passed through the API Gateway where they canbe

(not can be, divided. I think is just a typo)

Point 6. There is like a white line above the last row.

running locally failure due to server task missed in gulpfile.js

Hi:
Under directory ...\website, running command " gulp server", I got Task 'server' is not in your gulpfile

Bad performance in lambda functions

Hello,
I just deployed this example, but the functions of lambda are taking too much time. Is taking 1.6 seconds in getting only one post result. Any idea to improve this performance??

Thanks

Unable to delete and complete Todo

When you login and attempt to delete(or complete) a todo, it just logs you out of the console.

Reproduction Steps

Login and Create a Todo, and then attempt to delete(complete) it. It will send you back to the login page.

// todo-src/completeTodo, delteTodo/app.js
  if (!isValidRequest(context, event)) {
    metrics.putMetric('Error', 1, Unit.Count);
    return response(400, { message: 'Error: Invalid request' });
  }

Error Log

ERROR	Invoke Error 
{
    "errorType": "TypeError",
    "errorMessage": "Cannot read property 'id' of undefined",
    "stack": [
        "TypeError: Cannot read property 'id' of undefined",
        "    at isValidRequest (/var/task/app.js:36:26)",
        "    at /var/task/app.js:74:8",
        "    at /var/task/node_modules/aws-embedded-metrics/lib/logger/MetricScope.js:35:42",
        "    at Generator.next (<anonymous>)",
        "    at /var/task/node_modules/aws-embedded-metrics/lib/logger/MetricScope.js:22:71",
        "    at new Promise (<anonymous>)",
        "    at __awaiter (/var/task/node_modules/aws-embedded-metrics/lib/logger/MetricScope.js:18:12)",
        "    at Runtime.wrappedHandler [as handler] (/var/task/node_modules/aws-embedded-metrics/lib/logger/MetricScope.js:32:41)",
        "    at Runtime.handleOnce (/var/runtime/Runtime.js:66:25)"
    ]
}

Environment

• SAM CLI Version :
• OS :
• Language :

Other

Like addTodo, updateTodo, getTodo
  // if (!isValidRequest(context, event)) {
  if (!isValidRequest(event)) {
    metrics.putMetric('Error', 1, Unit.Count);
    return response(400, { message: 'Error: Invalid request' });
  }

---

This is 🐛 Bug Report

CORS policy error after login

Hello,

After deploying the webapp, when I sign up and then login, the page that is in the screenshot (attached) appears briefly then I get redirected to the login page again.

This seem to be an issue with the CORS policy, do you know how I can solve this?

Thank you!

Reproduction Steps

Error Log

Environment

• SAM CLI Version :
• OS :
• Language :

Other

---

This is 🐛 Bug Report

Rename CF template

Lets rename the CF template to lambda_webapp.template or something, Just keeping the same format as the other refarchs. Thanks

Template miss spell

miss spell in template.yml

not exist 'todo-src/completeToDo/'

lambda-refarch-webapp/template.yaml

Line 193 in fe9a34a

CodeUri: todo-src/completeToDo/

      Properties:
-        CodeUri: todo-src/completeToDo/
+        CodeUri: todo-src/completeTodo/
        Handler: app.completeToDoItem

CognitoID / aws_user_pools_id config on client unused?

The CognitoID output by the template is used to populate the aws_user_pools_id config on the client. This isn't referenced anywhere, and it seems to be redundant with the Cognito API token. Is there any use for this config?

lambda-refarch-webapp/template.yaml

Lines 369 to 371 in a9ced65

	CognitoID:
	Description: The Cognito UserPool ID
	Value: !Ref TodoUserPool

and

lambda-refarch-webapp/www/src/config.js

Line 6 in a9ced65

"aws_user_pools_id": "None", // CognitoID

Runtime version should be specified in helper files

config-helper.template
cognito-creation-helper.template

Replace "Runtime": "nodejs" with "Runtime": "nodejs4.3"

Frontend headers generation source

After couple hours of gooling and code examination (frontend) it's still unknown how headers are generated.

"Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3", "accept-encoding": "gzip, deflate, br", "Accept-Language": "en-US,en;q=0.9,pt-BR;q=0.8,pt;q=0.7,es-CO;q=0.6,es;q=0.5,zh-CN;q=0.4,zh;q=0.3", "cache-control": "max-age=0", "CloudFront-Forwarded-Proto": "https", "CloudFront-Is-Desktop-Viewer": "true", "CloudFront-Is-Mobile-Viewer": "false", "CloudFront-Is-SmartTV-Viewer": "false", "CloudFront-Is-Tablet-Viewer": "false", "CloudFront-Viewer-Country": "US", "Host": "asdasd.execute-api.us-east-1.amazonaws.com", "sec-fetch-mode": "navigate", "sec-fetch-site": "none", "sec-fetch-user": "?1", "upgrade-insecure-requests": "1", "User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/78.0.3904.70 Safari/537.36", "Via": "2.0 af59cbeda88e3a41b2689a63q4f61c64d.cloudfront.net (CloudFront)", "X-Amz-Cf-Id": "NzOz5TfgbqItgmy_C2Zj4TjAnkqMteY-aNMmshY4W9TZ1U-rJr5LHWw==", "X-Amzn-Trace-Id": "Root=1-5dc86974-035aeec025a456001d3ac4b6cb", "X-Forwarded-For": "72.21.196.66, 54.239.145.80", "X-Forwarded-Port": "443", "X-Forwarded-Proto": "https"

There also no documentation for this. any chance getting the answer or direction to dig?
Thanks

After deploy, AWS Amplify needs to be run manually

Hello

When I use the deploy script, the AWS Amplify app is not immediately functional:
I need to go manually through the AWS UI and click on "run build"

Is this expected? Or is there something I am missing?
Thanks!

Reproduction Steps

Error Log

Environment

• SAM CLI Version :
• OS :
• Language :

Other

---

This is 🐛 Bug Report

Lambda Vote function fails..

Keep getting message "TypeError: Cannot call method 'toUpperCase' of undefined at exports.handler (/var/task/app.js:11:32)" from votingapp lambda function.

API Gateway has 'request body passthrough' set to "When there are no templates defined", but fails with all other settings..

Dynamo Trigger throws Error

Cannot access stream arn:aws:dynamodb:us-east-1:6641*************:table/VoteApp/stream/2016-08-03T08:24:05.612. Please ensure the role can perform the GetRecords, GetShardIterator, DescribeStream, and ListStreams Actions on your stream in IAM. (Service: AWSLambda; Status Code: 400; Error Code: InvalidParameterValueException; Request ID: bc964133-5********************)

More real world

https://github.com/aws-samples/lambda-refarch-webapp/tree/master/todo-src doesn't share any code between the functions. This is a little detached from reality!

Unable to test locally

Reproduction Steps

(ins)[hendry@t14s todo-src]$ npm run test

> [email protected] test
> mocha tests/unit/

Error: No test files found: "tests/unit/"

I also tried following the steps in the README, but the dynamodb create-table line doesn't work

(ins)[hendry@t14s ~]$ aws dynamodb create-table --table-name TodoTable --attribute-definitions AttributeName=id,AttributeType=S --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST --endpoint-url http://127.0.0.1:8000

You must specify a region. You can also configure your region by running "aws configure".
(ins)[hendry@t14s ~]$ aws --region ap-southeast-1 dynamodb create-table --table-name TodoTable --attribute-definitions AttributeName=id,AttributeType=S --key-schema AttributeName=id,KeyType=HASH --billing-mode PAY_PER_REQUEST --endpoint-url http://127.0.0.1:8000

Unable to locate credentials. You can configure credentials by running "aws configure".
(ins)[hendry@t14s ~]$ aws --version
aws-cli/2.2.39 Python/3.8.8 Linux/5.14.8-arch1-1 exe/x86_64.arch prompt/off

This is 🐛 Bug Report

link to diagram in READ.md failing

It's failing with the following message:

<Error> <Code>AllAccessDisabled</Code> <Message>All access to this object has been disabled</Message> <RequestId>D4E69E7C80C26889</RequestId> <HostId> Co6bADFBvbqEXJHx3SnTb0VA9Eb8yFQjpw1/m4Fuk0Ro5aQZ2dIgIpzZ7joQ1weFBnti2BD5bY0= </HostId> </Error>

Unable to launch stack

Firstly, great effort in putting up the reference architecture, well done guys!

I have been trying to launch the stack recently to no avail.

I was using a user with admin role, and subsequently a root user (this is for my personal account, and I know this is a security risk). I used the default setting during the launch, I did not use IAM role to launch the stack.

This is the error when I click on the stack in Cloud Formation:

ROLLBACK_IN_PROGRESS AWS::CloudFormation::Stack serverless-web-refarch The following resource(s) failed to create: [DDBConfigTable, LambdaToDynamoDBUserTableRole, WebsiteBucket]. . Rollback requested by user.

What could be the issue and how can I get around the error?

Thanks!

Unsecure - User token passed in URL

Currently the user token appears in the URL. When user gets authenticated Amazon Cognito generates a token and returns it to the website in the URL as a parameter.
This is not best security practice.
Is there a better (more secure) way of passing that token?

Cloud formation stack giving error...please help

11:33:49 UTC-0400	CREATE_FAILED	AWS::CloudFormation::Stack	ConfigHelperStack	Embedded stack arn:aws:cloudformation:us-east-1:570585003507:stack/serverless-web-refarch-2-ConfigHelperStack-U9F0YSLGOX2J/b6b718b0-9827-11e9-8a12-0a3a983b5e88 was not successfully created: The following resource(s) failed to create: [AddConfigSetting].
	Physical ID:arn:aws:cloudformation:us-east-1:570585003507:stack/serverless-web-refarch-2-ConfigHelperStack-U9F0YSLGOX2J/b6b718b0-9827-11e9-8a12-0a3a983b5e88
	Client Request Token:Console-CreateStack-402d458e-2c3a-4308-b72d-eafefd5f4150

Nodejs runtime

Please merge nodejs runtime error into

https://s3.amazonaws.com/awslambda-serverless-web-refarch/serverless-web-master.template

I want to have a try.

cloudformation failed at confighelperstack

ConfigHelperStack has failed with a reason.

Embedded stack arn:aws:cloudformation:us-east-1:696770747654:stack/serverless-web-refarch-ConfigHelperStack-IR7BHVLQ0B2V/df2f9280-13c6-11e9-b19b-12967e4454e6 was not successfully created: The following resource(s) failed to create: [AddConfigSetting].

This may be caused by the setting here.

lambda-refarch-webapp/cloudformation/config-helper.template

Line 14 in 600f498

"AddConfigSetting": {

I don't know what caused this.

Unable to delete the Todo

description of the bug:
When you login and attempt to delete a todo, it just logs you out of the console. I am able to add and complete todo's but not delete them. I've pasted the traceback that I'm getting in X-ray.

Reproduction Steps

minimal amount of code that causes the bug (if possible) or a reference:
Login and Create a Todo, and then attempt to delete it. It will send you back to the login page.

Error Log

what is the error message you are seeing?
Xray Trace:

MissingRequiredParameter: Missing required key 'Key' in params
at features.constructor.captureAWSRequest [as customRequestHandler] (/var/task/node_modules/aws-xray-sdk-core/lib/patchers/aws_p.js:77)
at features.constructor.addAllRequestListeners (/var/task/node_modules/aws-sdk/lib/service.js:279)
at features.constructor.makeRequest (/var/task/node_modules/aws-sdk/lib/service.js:203)
at features.constructor.svc.<computed> [as deleteItem] (/var/task/node_modules/aws-sdk/lib/service.js:685)
at DocumentClient.makeServiceRequest (/var/task/node_modules/aws-sdk/lib/dynamodb/document_client.js:100)
at DocumentClient.delete (/var/task/node_modules/aws-sdk/lib/dynamodb/document_client.js:237)
at deleteRecordById (/var/task/app.js:57)
at anonymous (/var/task/app.js:75)
at anonymous (/var/task/node_modules/aws-embedded-metrics/lib/logger/MetricScope.js:35)
at Generator.next (<anonymous>)

Environment

• SAM CLI Version :
• OS :
• Language :

Other

---

This is 🐛 Bug Report

Question regarding pricing

Hi, I am interested in knowing how would one calculate or estimate the cost associated to running this application.

Regions are inconsistent in code

The CFN template mentions/assumes you'll deploy into us-east-1, however the Lambda function for receiving votes has us-west-2 hardcoded on line 7. It'd be good to either parameterise that, or to call it out in the README.

Add overview of DynamoDB design

The design of the storage + indexes for DynamoDB isn't clear. Could the README.md be updated to explain the way the data is stored?

Aggregation function is missing a trigger

The aggregation function needs to be hung off the DynamoDB table "Votes" being updated. This isn't currently handled in the CFN template nor the README.md. Possibly best to do the latter with some guidance around batch sizing/etc.