Ember Serverless on AWS

A Serverless Ember.js application running on AWS. It utilizes a fully serverless architecture:

• Cognito User Pools for authentication, registration, and confirmation
• API Gateway for REST API authenticated with Cognito User Pools
• Lambda and DynamoDB as a Backend
• CloudFormation and SAM for Infrastructure management

The application utilizes Ember.js methodology by abstracting API Gateway communication into adapters, allowing you to write controller code utilizing ember models. The API Gateway SDK that is generated from API Gateway can easily be replaced if you update your API by simple replacing the vendor/apiGateway-js-sdk with the generated one from API Gateway. Lambda functions can easily be updated by running the included cloud/deploy.sh bash script which simply runs the appropriate cloudformation commands for you.

Prerequisites

You will need the following things properly installed on your computer.

• Git
• Node.js (with NPM)
• Bower
• AWS CLI
• Ember CLI

Installation

• git clone https://github.com/awslabs/aws-serverless-ember
• cd client
• npm install && bower install

Creating the AWS Infrastructure

Please NOTE: the following steps will incur charges on your AWS account, please see the appropriate pricing pages for the services

First, run the hosting template which will create the S3 infrastructure for hosting the web app and your deployed lambda code:

cd cloud
aws cloudformation deploy --template-file hosting.yaml --stack-name ember-serverless-hosting --capabilities CAPABILITY_IAM

Once this completes, get the outputs from the template:

aws cloudformation describe-stacks --stack-name ember-serverless-hosting

Note the OutputValue value for the CodeBucketName S3 bucket, this will be the bucket we use to deploy our Lambda code to. Now create the API using the included deploy script to package and deploy the Lambda code, API Gateway, and DynamoDB table:

./deploy.sh --stack-name ember-serverless-api --template api.yaml --bucket <<bucket-name-from-above-output>>

This will package the api.yaml template file and output an api-deploy.yaml file. This file will contain the S3 location of the automatically packaged Lambda code and template. It will then deploy the CloudFormation stack by creating a changeset. Once complete, run describe again to see the outputs:

aws cloudformation describe-stacks --stack-name ember-serverless-api

Note the Outputs which will contain your newly created API Gateway REST API ID which will be used to CRUD DyanmoDB items.

Now, run the following to retrieve the JavaScript SDK for your newly created API:

aws apigateway get-sdk --rest-api-id <<rest-api-id-from-above>> --stage-name Prod --sdk-type javascript ./apiGateway-js-sdk.zip

This downloads a .zip file that contains the JavaScript interface generated by API Gateway. You use this interface to interact with API Gateway from your Ember.js application. Extract the contents of the .zip file, which produces a folder named apiGateway-js-sdk directly into your client/vendor/ folder. You should have the following folder structure:

• client
  • vendor
    • apiGateway-js-sdk
    • amazon-cognito

Update Client Environment Variables

Open your client/config/environment.js file and add your AWS configuration to the development section. Add the region in which you are running, the Amazon Cognito identity pool ID created in the previous section, the Amazon Cognito user pool ID created in the previous section, and the user pool app client ID created in the previous section.

// client/config/environment.js L26
if (environment === 'development') {
    ENV.AWS_REGION = ‘aws-region-1’
    ENV.AWS_POOL_ID = ‘aws-region:unique-hash-id’
    ENV.AWS_USER_POOL_ID = ‘aws-region_unique-id’
    ENV.AWS_CLIENT_ID = ‘unique-user-pool-app-id’
}

You can retrieve these values by running:

aws cloudformation describe-stacks --stack-name ember-serverless-api

Use the following values returned in the Output:

ENV.AWS_POOL_ID -> CognitoIdentityPoolId
ENV.AWS_USER_POOL_ID -> CognitoUserPoolsId
ENV.AWS_CLIENT_ID -> CognitoUserPoolsClientId

Running / Development

• ember serve
• Visit your app at http://localhost:4200.

Code Generators

Make use of the many generators for code, try ember help generate for more details

Running Tests

• ember test
• ember test --server

Building

• ember build (development)
• ember build --environment production (production)

Deploying the Web Application

Build the ember app and copy it to S3, note you'll need the "WebsiteBucket" output value from the above hosting cloudformation stack you generated. If you need it again, just run aws cloudformation describe-stacks --stack-name ember-serverless-hosting *if you used a different name, substitute that in-place of "ember-serverless-hosting", then note the OutputValue for "WebsiteBucket" and use that here:

cd client
ember build
aws s3 sync dist/ s3://<<your-ember-website-bucket>>/ -acl public-read

Once synced you can visit the URL for your S3 bucket using the OutputValue from the hosting template for WebsiteURL.

Further Reading / Useful Links

• ember.js
• ember-cli
• aws-cli
• Development Browser Extensions
  • ember inspector for chrome
  • ember inspector for firefox