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!

Serverless Archictecture Boilerplate with Go?

Looking for boilerplates to organize big projects using AWS Lambda with Go? 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