⚡ serverless monorepo stack ⚡

This project was bootstrapped with starterstack, a Serverless monorepo template architecture.

OS support for local development

• Windows (WSL or Git Bash)
• macOS including M1
• Linux

Prerequisites

• Node 20
• Python 3.12
• graphviz to generate docs
• sam cli to deploy locally
• aws cli to deploy locally
• jq to deploy locally

Developer tool prerequisites if not using Docker

• go Go for shfmt
• shfmt to format shell scripts
• black to format python

Windows Git Bash prerequisites

• Git Bash make sure symbolic links are enabled
• git clone -c core.symlinks=true

Recommended

• nvm
• direnv

Roadmap

• Template repository with quick setup script
• CloudFront CDN supporting static, dynamic, private content, REST API (REST, GraphQL + subscriptions), and WebSockets
• Optional WAF (REST API, CloudFront)
• Create React App with SSR support, protected assets and sourcemaps
• Direct S3 file uploads
• Image resizing example (jpeg, and webp)
• PDF example
• CloudFront functions
• Custom Lambda Authorizers for HTTP API, REST API & Websockets using JWT and DynamoDB with user roles
• X-Ray tracing, sampled debug logging, and correlationId tracing
• Examples for DynamoDB, SES (sending and receiving), SNS, SSM, S3, EventBridge
• Custom CloudFormation resource supporting SES automation
• Language and device support for content
• Single AWS account, and AWS account per stage support
• DynamoDB streams
• DynamoDB migrations
• EventBridge Pipes
• Sanity tests with Step Functions
• 100% SAM templates
• No Terraform
• No Lambda Containers
• Deploy using sam-expand
• Github Action deploys using the principle of least privilege
• Infrastructure audit using sls-mentor
• Feature branch deployment support
• IAM role for deployment using OpenID Connect (no aws keys needed)
• Manual DNS entry of Nameservers
• Node, and Python examples
• Budget alerts to SNS and Slack
• Optional CloudWatch alarms
• Sentry integration

Git commits

Commit messages are Commitizen friendly

npx cz or npm run cz should be used instead of git commit

License

Apache License, Version 2.0

🏠 development

npm i

proxy to deployed environment, with or without local web

npm run proxy

graphql introspection for developer users

• GraphQL - You can use apollo studio and connect it to a local running graphql server without exposing a playground.

misc scripts

npm pkg get scripts

Initial AWS setup

• create repository from starterstack repository template
• create a starterstack PAT (personal access token) with (repo, write:packages, and delete:packages) make a note of the value, this will be used to cleanup feature deployments
• install prerequisites
• git clone
• cd starterstack

• npm i
  npm run setup # add the PATs, select generate random values for the API secrets, AWS secrets are to be skipped for now

• push changes
• deploy deployment, monitoring, iam and stack on each AWS account to be used by each stage deploy log account first, then backup, then the others

  launch AWS CloudShell in the AWS console
  git clone https://github.com/starterstack/starterstack.git
  <your username>
  <your PAT with read permissions or password>
  cd starterstack
  npm ci --ignore-scripts --omit=dev
  # if cloudshell runs out of space use `npm run cli` with AWS credentials instead
  cd packages/deployment # repeat build/lint/deploy for all regions
  npx sam-expand build
  npx sam-expand deploy
  cd -
  cd packages/monitoring # repeat build/lint/deploy for all regions
  npx sam-expand build
  npx sam-expand deploy
  cd -
  cd packages/iam
  npx sam-expand build
  npx sam-expand deploy
  cd -
  cd packages/stack # skip this step for log and backup accounts
  npx sam-expand build
  npx sam-expand deploy
  # when the stack is being created access aws console, and follow the DNS instructions below
  cd -
  cd packages/cloudtrail # for log account only
  npx sam-expand build
  npx sam-expand deploy
  cd -
  cd packages/backup # for backup account only
  npx sam-expand build
  npx sam-expand deploy
  # if log or backup account run `npm run setup # GitHub secrets only` to save s3 bucket to secrets from cloudformation output

• when backup and log are deployed with sam-expand, push changes and wait for GitHub actions before continuing
• skip following dns steps for log and backup accounts
• make note of the name servers in route53
• shorten all TTL in both your DNS provider and route53 for all non prod accounts
• add NS records for dev., feature., and root domain in your DNS provider this may take some time to propagate
• setup GitHub secrets

  # for log and backup make sure you have the correct credentials if not using cloudshell, and that you select log, or backup for `Update secrets for stage` prompt
  npm run setup # skip to secrets only, use the PAT value from above, select generate random values for the API secrets, select use cloudformation for ci roles

• git push

• enable security, and dependabot settings
• to send mails with SES you'll need to request SES production access on (dev, prod, and test accounts)

CI/CD

Deployment with npx sam-expand using GitHub actions.

See deployments for active environments.

Merge release please pull requests before deploying to production, they are in the format chore(main): release x

• deploy PR to own stage with optional label feature deploy
• each push to main deploys to dev stage
• deploy to production by running workflow main.yml with (stage: prod, account: production)

Shared javascript code

Common javascript code is found in packages/shared.

To use any of the files in the lambda use symlinks, add the dependencies to the function, and to root as a devDependency.

ln -s <js file path to shared file> <js file path in lambda function>

Cloud Nuke 🔥

Before running cloud-nuke we should remove our CloudFormation stacks.

• run delete feature workflow for all environments on account to nuke
• launch AWS CloudShell in the AWS console

  launch AWS CloudShell in the AWS console
  git clone https://github.com/starterstack/starterstack.git
  <your username>
  <your PAT with read permissions or password>
  cd starterstack
  npm ci --ignore-scripts --omit=dev
  # possible manual intervension required to succesfully delete CloudFormation stacks
  cd packages/stack
  npx sam-expand delete
  cd ../iam
  npx sam-expand delete

• if you want to recreate refer to the Initial setup section

Tags

All resources are tagged with ManagedBy starterstack, and Name

It's a good idea enabling these using Cost Allocation Tags

If and when new resource types are added, missing tags can be detected using Tag Editor

The extra work to tag resources is as follows

• tag eventbus rules script (not supported yet in CloudFormation)
• default tags are defined here

Manually deleting a CloudFormation stack

GitHub workflows won't detect git commits including deletion of entire cloudformation stacks, CloudShell can be used to remove the stacks manually.

launch AWS CloudShell in the AWS console
git clone https://github.com/starterstack/starterstack.git
<your username>
<your PAT with read permissions or password>
cd starterstack
git checkout <commit prior to delete>
npm ci --ignore-scripts --omit=dev
cd packages/<stack to delete>
npx sam-expand remove

DynamoDB

createdAt, createdBy, modifiedBy, modifiedAt are automatically added to write queries in dynamodb.js using aws-sdk-v3's middleware stack, userId is populated from correlationIds.

Overview

Overview diagram

CloudFormation stacks

  graph LR;
    backup --- deployment
    backup --- monitoring
    budget --- deployment
    budget --- monitoring
    cdn --- deployment
    cdn --- monitoring
    cdn --- stack
    cdn --- cloudformation
    cdn --- region
    cdn --- media
    cdn --- rest
    cdn --- web
    cdn --- graphql
    cloudtrail --- deployment
    cloudtrail --- monitoring
    deployment --- monitoring
    dynamodb --- deployment
    dynamodb --- monitoring
    dynamodb-stack-audit --- deployment
    dynamodb-stack-audit --- monitoring
    dynamodb-stack-audit --- eventbus
    dynamodb-stack-audit --- dynamodb
    eventbus --- deployment
    eventbus --- monitoring
    graphql --- deployment
    graphql --- monitoring
    graphql --- dynamodb
    graphql --- stage
    graphql --- eventbus
    iam --- deployment
    iam --- monitoring
    media --- deployment
    media --- monitoring
    media --- dynamodb
    media --- eventbus
    monitoring --- deployment
    notification --- deployment
    notification --- monitoring
    notification --- eventbus
    notification --- ses
    region --- deployment
    region --- monitoring
    rest --- deployment
    rest --- monitoring
    rest --- dynamodb
    rest --- stage
    rest --- eventbus
    ses --- deployment
    ses --- monitoring
    ses --- eventbus
    ses --- stack
    stack --- deployment
    stack --- monitoring
    stage --- deployment
    stage --- monitoring
    stage --- dynamodb
    test --- deployment
    test --- monitoring
    test --- eventbus
    test --- dynamodb
    test --- media
    tracking --- deployment
    tracking --- monitoring
    tracking --- dynamodb
    tracking --- eventbus
    web --- deployment
    web --- monitoring
    web --- stage

UML diagrams

drag drawio file to app.diagrams.net

Interactive documentation using structurizr.

• diagrams use the c4 model.
• markdown files in ./docs/structurizr/doc are served as documentation.
• architectural descision record files in ./docs/structurizr/doc/adr.
• documentation uses structurizr/lite.

To run then structurizr documentation run npm run docs

To create new architectural descision record files use the adr cli.

The workspace dsl file using structurizr dsl format contains the diagram dsl.