Note 11/21/2017, there is a pending bug with
Serverless Application Model (SAM) and Usage Plan's in cloudformation. There is a work around that will be added shortly
Update 11/27/2017 The issue has been fixed with latest commit
Note 11/27/2017 An enhancement to the template is address usage plan being globla. This means the script cannot be run for multiple environments
- Can only deploy to one environment based on usage plan
This project is based on the AWSLabs Servless project for Nodejs Express applications and AWS Lambda awslabs aws-serverless-express
It builds on top of the quick start guide found under the example folder example
In addition to a basic Lambda function and Express server, the project includes a Swagger file, CloudFormation template with Serverless Application Model (SAM), and helper scripts to help you set up and manage your application.
In additional to the awslabs boilerplate this also contains the needed cloudformation configuration to create separate environments (stages) for a CI process, integration with aws Route 53 for friendly API naming, as well as an example Usage Plan for distributing API's
This required changes to the scripts configure.js deconfigure.js and package.json files to add the additional parameters (hostedzone, dnsname, and stage) to the cloudformation template for deployment
This guide assumes you already have
- set up an AWS account
- have the latest version of the AWS CLI installed.
- A hosted zone named created in AWS Route 53
- From your preferred project directory:
git clone https://github.com/vernonsoftwaresolutions/aws-serverless-nodejs-boilerplate.git && cd aws-serverless-nodejs-boilerplate
. - Run
npm run config -- --account-id="<accountId>" --bucket-name="<bucketName>" --dnsname="<dnsname>" --hostedzonename="<hostedzone>" --stage="<stage>" [--region="<region>" --function-name="<functionName>"]
to configure the example, eg.npm run config -- --account-id="123456789012" --bucket-name="my-unique-bucket"
. This modifiespackage.json
,simple-proxy-api.yaml
andcloudformation.yaml
with your account ID, bucket, region, function name, hostedzone, dnsname, and stage (region defaults tous-east-1
and function name defaults toAwsServerlessExpressFunction
). If the bucket you specify does not yet exist, the next step will create it for you. This step modifies the existing files in-place; if you wish to make changes to these settings, you will need to modifypackage.json
,simple-proxy-api.yaml
andcloudformation.yaml
manually. - Run
npm run setup
(Windows users:npm run win-setup
) - this installs the node dependencies, creates an S3 bucket (if it does not already exist), packages and deploys your serverless Express application to AWS Lambda, and creates an API Gateway proxy API. - After the setup command completes, open the AWS CloudFormation console https://console.aws.amazon.com/cloudformation/home and switch to the region you specified. Select the
AwsServerlessExpressStack
stack, then click theApiUrl
value under the Outputs section - this will open a new page with your running API. The API index lists the resources available in the example Express server (app.js
), along with examplecurl
commands.
See the sections below for details on how to migrate an existing (or create a new) Node.js project based on this example. If you would prefer to delete AWS assets that were just created, simply run npm run delete-stack
to delete the CloudFormation Stack, including the API and Lambda Function. If you specified a new bucket in the config
command for step 1 and want to delete that bucket, run npm run delete-bucket
.
To use this example as a base for a new Node.js project:
- Copy the files in the
example
directory into a new project directory (cp -r ./example ~/projects/my-new-node-project
). If you have not already done so, follow the steps for running the example (you may want to first modify some of the resource names to something more project-specific, eg. the CloudFormation stack, Lambda function, and API Gateway API). - After making updates to
app.js
, simply runnpm run package-deploy
(Windows users:npm run win-package-deploy
).
To migrate an existing Node server:
- Copy the following files from the
example
directory:api-gateway-event.json
,cloudformation.yaml
,lambda.js
, andsimple-proxy-api.yaml
. Additionally, copy thescripts
andconfig
sections ofexample/package.json
into your existingpackage.json
- this includes many helpful commands to manage your AWS serverless assets and perform basic local simulation of API Gateway and Lambda. If you have not already done so, follow the steps for running the example (be sure to copy overscripts/configure.js
. You may want to first modify some of the resource names to something more project-specific, eg. the CloudFormation stack, Lambda function, and API Gateway API). - From your existing project directory, run
npm install --save aws-serverless-express
. - Modify
lambda.js
to import your own server configuration (eg. changerequire('./app')
torequire('./server')
). You will need to ensure you export your app configuration from the necessary file (eg.module.exports = app
). This library takes your app configuration and listens on a Unix Domain Socket for you, so you can remove your call toapp.listen()
(if you have aserver.listen
callback, you can provide it as the second parameter in theawsServerlessExpress.createServer
method). - Modify the
CodeUri
property of the Lambda function resource incloudformation.yaml
to point to your application directory (e.g.CodeUri: ./src
). If you are using a build tool (e.g. Gulp, Grunt, Webpack, Rollup, etc.), you will instead want to point to your build output directory. - Run
npm run package-deploy
(Windows users:npm run win-package-deploy
) to package and deploy your application.
To perform a basic, local simulation of API Gateway and Lambda with your Node server, update api-gateway-event.json
with some values that are valid for your server (httpMethod
, path
, body
etc.) and run npm run local
. AWS Lambda uses NodeJS 4.3 LTS, and it is recommended to use the same version for testing purposes.
If you need to make modifications to your API Gateway API, modify simple-proxy-api.yaml
and run npm run package-deploy
. If your API requires CORS, be sure to modify the two options
methods defined in the Swagger file, otherwise you can safely remove them. To modify your other AWS assets, make your changes to cloudformation.yaml
and run npm run package-deploy
. Alternatively, you can manage these assets via the AWS console.
This example was written against Node.js version 6.10