Skip to content

Latest commit

 

History

History
51 lines (35 loc) · 4.31 KB

README.md

File metadata and controls

51 lines (35 loc) · 4.31 KB
Raw

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.