Serverless API starter template

This project is a GitHub template you can initiate new projects with. Its aim is to provide a robust serverless development, deployment, and testing experience out-of-the-box so that developers can focus on writing business logic and develop their serverless app with confidence.

If you find yourself making changes to the default setup in your project please consider making those same changes in this template repository so that future developers can benefit from better ways of doing things.

1. Template overview
2. 3rd party setup & configuration
   1. AWS
   2. Lumigo
   3. CircleCI
3. Local setup & deployment
4. Application architecture
5. CI/CD overview
6. Project stats

Template overview

How to use this template

1. Follow the steps here to create a new repo/project from this template
2. Modify the code as-needed for your new service (including this README!)

Tools & technologies used

• Serverless Framework for managing infrastructure as code (including helpful abstractions on top of CloudFormation) and as a CLI for scripted deployments
• TypeScript for a better JavaScripting experience
• Jest for unit and e2e tests
• ESLint and Prettier for code rules and styling
• CircleCI config for CI/CD
• Lumigo for serverless monitoring and alerting
• A handful of helpful plugins for the Serverless Framework
• Examples of using the AWS JavaScript SDK to access deployed resources like DynamoDB

Key limitations

• Lambda limits
• Serverless Framework works best with CloudFormation, see CloudFormation limits
• CloudFront limits
• DynamoDB limits

Template TODOs

• Add a custom Lambda Authorizer function to validate that calls are from authenticated/authorized users
• Add encrypted environment variables using KMS or SSM

3rd party setup & configuration

AWS setup & configuration

To deploy the application to AWS you'll need an account with access credentials configured locally - see the Serverless Framework credentials guide. Setting up the full AWS CLI and configuring access via profiles is recommended, as it will allow you to access AWS resources directly when needed.

Lumigo setup & configuration

This application is currently setup with Lumigo as a serverless monitoring and logging solution. To package and deploy the application you'll either need to setup an account and provide a Lumigo access token as environment variable (or .env file - see Application Setup below).

Follow these instructions for setting up your Lumigo account and configuring the Lumigo serverless plugin.

If you don't want to use Lumigo or want to get started without it just comment out the Lumigo plugin in serverless.yml, and optionally comment out the Lumigo-specific configurations:

plugins:
  - serverless-webpack
  - serverless-cloudformation-resource-counter
  - serverless-plugin-iam-checker
  - serverless-plugin-test-helper
  - serverless-prune-plugin
  # - serverless-lumigo

# (commenting out the custom config is optional)
custom:
  ...
  # https://github.com/lumigo-io/serverless-lumigo-plugin
  # lumigo:
  # token: ${env:LUMIGO_TOKEN}
  # nodePackageManager: npm

CircleCI setup & configurations

This application is setup with CircleCI for testing and deployments. See their documentation for steps on getting started.

Local setup & deployment

Setup local environment

If using Lumigo, create a .env file with the following:

LUMIGO_TOKEN=<token>

Install dependencies

npm i

Generate and view OpenAPI docs

# Generate OpenAPI documentation
npm run generate-docs

# Run a live server at localhost:8080
npm run serve-docs

Deploy application to AWS*

# Using your default AWS profile
npm run deploy

# Using a named AWS profile to a specific stage
npm run deploy -- --aws-profile [PROFILE] --stage [STAGE]

*Note that deploying the application for the first time to a permanent stage (prod, staging, dev) can take up to 1 hour. This is because the application makes use of CloudFront for CDN-level API caching, and when CloudFront creates a new distribution it takes a long time. This means that when CircleCI is deploying the application to a permanent stage for the first time it will fail due to a CircleCI timeout. While CircleCI errors out the deployment continues via CloudFormation, and once the first deploy has completed subsequent deploys will complete much faster (assuming no changes to the CloudFront configurations).

Load snapshot data from app/messages/sample-data/valid-messages.json into the deployed DynamoDB table

# Using your default AWS profile
npm run load-data

# Using a named AWS profile and targeting a specific stage
npm run load-data -- --aws-profile [PROFILE] --stage [STAGE]

Run unit tests

npm test

Run e2e tests*

npm run e2e-test

*Note that E2E tests can only be run after a successful deployment. The serverless-plugin-test-helper writes a file to the .serverless directory with the dynamically generated URLs for Api Gateway & CloudFront (if deployed to a permanent stage) which can then be loaded into the test file using the same library.

Remove application from AWS

# Using your default AWS profile
npm run remove

# Using a named AWS profile for a specific stage
npm run remove -- --aws-profile [PROFILE] --stage [STAGE]

Note that all of the serverless commands are run through package.json scripts - this is so that people are working from a pinned version of the serverless framework as included in the package, as opposed to everyone using a global version that could span versions across multiple developer environments, potentially with slightly different side effects or other unintended differences that introduces unnecessary variance.

Application architecture

Permanent stages

Permanent stages (dev, staging, and prod) have two endpoints available for calling the API - one via API Gateway directly, and one via CloudFront. Note that calling the API Gateway directly bypasses CDN caching and so won't show performance benefits on subsequent calls.

Ephemeral stages

Ephemeral stages have one endpoint available for calling the API - the one generated by API Gateway.

API Endpoints

To see the endpoints check the output section of the deployed CloudFormation stack. You can view them in the CloudFormation console or via the AWS CLI, etc.

API documentation

The api documentation is generated with OpenAPI and hosted on a repo-specific GitHub page.

CI/CD

For detailed information on how CI/CD works across branches and AWS accounts see the .circleci README here

Project stats

-------------------------------------------------------------------------------
Language                     files          blank        comment           code
-------------------------------------------------------------------------------
TypeScript                      20             94            158            653
YAML                             6             41             24            453
Markdown                         3            115              0            230
JSON                             4              0              0            166
JavaScript                       5              1              1             95
HTML                             1              1              4             20
-------------------------------------------------------------------------------
SUM:                            39            252            187           1617
-------------------------------------------------------------------------------

Generated using yarn run project-stats