Skip to content
Boilerplate to organize and deploy big projects using AWS API Gateway and AWS Lambda with Serverless Framework ⚡️ 🚀 ⚡️ 🚀
JavaScript Dockerfile
Branch: master
Clone or download
Latest commit d44b107 Aug 17, 2019

README.md

Logo

Serverless Architecture Boilerplate serverless License: MIT Build Status

CI / CD Pipeline

Need a Codepipeline Structure to deploy your Serverless Project with Quality? See this repo!

Structure

.
├── modules (modules folder)
│   └── books (module / context)
│       ├── endpoints (API endpoints)
│       │   ├── create.js
│       │   ├── delete.js
│       │   ├── read.js
│       │   └── update.js
│       └── functions (workers / background functions)
│           └── worker
│               └── handler.js
├── package.json
├── serverless.yml (serverless config)
├── handlers (functions config)
│   ├── books-endpoints.yml (endpoints config)
│   └── books-workers.yml (workers config)
├── shared (shared components)
│   └── lib (shared libraries)
│       ├── dynamo.js
│       ├── kinesis.js
│       ├── lambda.js
│       ├── parsers.js
│       ├── sqs.js
│       └── uuid.js
└── test (tests folder)
    └── unit (unit tests folder)
        ├── modules (unit tests for modules)
        │   └── books
        └── shared (unit tests for shared components)
            └── lib (unit tests for libraries)
                ├── dynamo.test.js
                ├── kinesis.test.js
                ├── parsers.test.js
                ├── sqs.test.js
                └── uuid.test.js

Functions

HTTP Trigger Function (API Gateway)

functions:

  # API Endpoints
  books-register:
    handler: modules/books/endpoints/create.create #Path to function
    memorySize: 128 # Lambda Memory Limit
    timeout: 60 # Lambda Timeout
    events: 
      - http: # HTTP Trigger 
          path: services/books # API Endpoint
          method: post # HTTP Method

Cloudwatch Events Functions (Cron)

Lambda Schedule Docs

# Background Function
  books-consumer:
    handler: modules/books/functions/worker/handler.worker #Path to function
    events:
      - schedule: #Cloudwatch Event Trigger
        rate: cron(* * * * * *) # Cron Syntax 
        enabled: true # Trigger Enabled

Development environment

This boilerplate uses serverless-local plugin and some containers and plugins to emulate the AWS Resources

docker-compose up

The applications will start on http://localhost:3000

Dev Plugins

This boilerplate contains following plugins for local development:

Production environment

Deploy full services

serverless deploy -v

asciicast

Deploy a function

serverless deploy function -f books-consumer

Get function logs

serverless books-consumer -f bananinha -t

Clean All

serverless remove

Testing

Create Book

curl -X POST \
    -H "Content-Type: application/json" \
    -d '{"title": "American Gods", "author": "Neil Gaiman", "price": 10.00  }' \
    https://yur25zhqo0.execute-api.us-east-1.amazonaws.com/production/services/books -i

List Books

curl -X GET \
    https://yur25zhqo0.execute-api.us-east-1.amazonaws.com/production/services/books

asciicast

Detail Book

curl -X GET \
    https://yur25zhqo0.execute-api.us-east-1.amazonaws.com/production/services/books/456c9e8f-6c50-d656-dc69-dc828c42af65

Delete Book

curl -X DELETE \
    https://yur25zhqo0.execute-api.us-east-1.amazonaws.com/production/services/books/456c9e8f-6c50-d656-dc69-dc828c42af65 -i 

Update Book

curl -X PUT \
    -d '{"title": "updated modafoca"}' -H "Content-type: application/json" \
    https://eusrv4mci5.execute-api.us-east-1.amazonaws.com/production/services/books/bbafdb0c-ee6e-fca0-f224-ed534f5b7766 -i

asciicast

Custom and Environment Variables

Custom Items

Creating and Using custom variables to build dynamic name

custom:
  region: ${self:provider.region} 
  stage: ${opt:stage, self:provider.stage}
  prefix: ${self:custom.stage}-${self:service}
  process: ${self:custom.prefix}-process
  config: ${self:custom.prefix}-config
  dynamo-books: ${self:custom.prefix}-BooksCatalog
  sns-logs: ${self:custom.prefix}-trigger-logs 
  sqs-logs: ${self:custom.prefix}-messages-logs

Environment Variables

Building URL Resources using CloudFormation parameters and Custom Variables

  environment: # Global Environment variables
    DYNAMO_TABLE_BOOKS: ${self:custom.dynamo-books} # Reference to Custom Env
    SQS_QUEUE_URL: 'https://sqs.${self:provider.region}.amazonaws.com/#{AWS::AccountId}/${self:custom.sqs-logs}'
    REGION: ${self:custom.region}

Manage AWS Cloudformation with Serverless

IAM Roles

IAM Docs

  iamRoleStatements: # Permissions for all of your functions can be set here

  - Effect: Allow
    Action: # Gives permission to DynamoDB tables in a specific region
      - dynamodb:DescribeTable
      - dynamodb:Query
      - dynamodb:Scan
      - dynamodb:GetItem
      - dynamodb:PutItem
      - dynamodb:UpdateItem
      - dynamodb:DeleteItem
    Resource: "arn:aws:dynamodb:us-east-1:*:*"

  - Effect: Allow
    Action: # Gives permission to Lambda execution
      - lambda:InvokeFunction
      - lambda:InvokeAsync
    Resource: "*"

Manage Infrastructure Components - Docs

# Infrastrucure - Cloud Formation
resources:  # CloudFormation template syntax

  Resources:
    #DynamoDB Books Table
    BooksCatalog:
      Type: AWS::DynamoDB::Table # CloudFormation Pseudo Parameter Example
      Properties:
        TableName: ${self:custom.dynamo-books}
        AttributeDefinitions:
          - AttributeName: hashkey
            AttributeType: S
        KeySchema:
          - AttributeName: hashkey
            KeyType: HASH
        ProvisionedThroughput:
          ReadCapacityUnits: 2
          WriteCapacityUnits: 1

    # SQS Queue to Update DynamoDB
    BooksQueueExample:
      Type: AWS::SQS::Queue
      Properties:
        QueueName: ${self:custom.sqs-logs}
        MessageRetentionPeriod: 1209600
        VisibilityTimeout: 60
You can’t perform that action at this time.