Skip to content
aws-blueprint REST API example using AWS SAM and NestJS
TypeScript Shell Makefile
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
aws add missing sam template Aug 13, 2019
docker docker communication Jul 31, 2019
docs/openapi
dynamodb initial Jul 30, 2019
node_modules initial Jul 31, 2019
src outputs Aug 1, 2019
test
.gitignore readme Aug 1, 2019
.yarnclean initial lambda Jul 31, 2019
LICENSE Initial commit Jul 29, 2019
Makefile
README.md readme Aug 13, 2019
dotenv.example readme Aug 1, 2019
nest-cli.json initial Jul 30, 2019
package.json rename pipeline params Jul 31, 2019
tsconfig.build.json initial Jul 30, 2019
tsconfig.json initial Jul 30, 2019
tslint.json initial Jul 30, 2019
yarn.lock docker communication Jul 31, 2019

README.md

abp-sam-nestjs

aws-blueprint example for a NestJS based API using AWS Serverless Application Module (SAM).

Features:

  • DynamoDB local with tools to create table(s) and load data.
  • Local dev server with hot-reload (quicker developer iterations than sam local).
  • Simulate API Gateway -> Lambda locally via sam local start-api. Talks to DynamoDB local via docker-compose.
  • Multi-stage CI/CD via CodePipeline. Convention over configuration, designed for teams and feature branches.
  • Straight forward environment variable configuration. Supports pulling from SSM when running in AWS.
  • Realtime CodePipeline source pulls via GitHub webhook.
  • NestJS configured to use the performant Fastify framework (vs default Express).

Prerequisites

  1. AWS CLI
  2. Create a github access token. This token will be used by the CI/CD to pull code. Required scopes: admin:repo_hook, public_repo, repo:status, repo_deployment.
  3. S3 bucket to hold Lambda deployment zips. Only need 1 bucket per AWS account.
  4. Docker
  5. An SNS topic for CI/CD code promotion approvals. Subscribe your email address to it.

Quickstart - local dev server with auto-reload

  1. cp dotenv.example .env
  2. make dynamo/init will load local DynamoDB with sample data (dropping table if exists).
  3. yarn install
  4. make run/local-dev-server will start server locally, and hot-reload on changes.
  5. Open http://127.0.0.1:8080/v1 If you look at the console you will see the app env vars. ENV_TEST is undefined? Keep reading...

Simulate APIG + Lambda locally

This repo utlizes sam local start-api cli to simulate APIG->Lambda->NestJS.

Enviornment variables are pulled from sam-template.yml::Environment.Variables (not .env). To simulate how these will be set in cloudformation, the --parameter-overrides sam option is used. See run/sam-start-api in Makefile for an example.

  1. make run/watch will compile typescript on file changes.
  2. In another terminal run make run/sam-start-api
  3. Open http://127.0.0.1:3000/v1 and look at the console for the app env vars.

Startup is slow right? This simulates Lambda cold starts. See here.

Deploying to AWS via CI/CD (AWS CodePipeline) using GitHub webhook

The parameter SomeSecretInSSM in sam-template.yml dictates where in SSM to pull a value, which is then set as an env var in the lambda (see SECRET_KEY in sam-template.yml). In CodePipeline you set the SomeSecretInSSM param value on a stage-by-stage basis aws/cloudformation/parameters. In test-pipeline-parameters.json you'll notice it is set to /test/abp-sam-nestjs/master/envs/SECRET_KEY. If you update the value in SSM, just execute a stack update to get the new env var into lambda.

  1. Clone this repo
  2. From SSM Console create a parameter /test/abp-sam-nestjs/master/envs/SECRET_KEY with any value you like.
  3. Create a CI/CD pipeline via CloudFormation using aws/cloudformation/pipeline.yml using the name abp-sam-nestjs--master--api--cicd (naming convention is [gitrepo]--[branch]--[eyecatcher]--cicd)
  4. git push and watch the pipeline. Will need to approve to promote to next stage. URL to your API is in the outputs of the ExecuteChangeSet CloudFormation.
You can’t perform that action at this time.