{"id":23170146,"url":"https://github.com/alhazmy13/aws-serverless-skeleton","last_synced_at":"2025-06-21T01:41:29.226Z","repository":{"id":46769358,"uuid":"179161279","full_name":"alhazmy13/aws-serverless-skeleton","owner":"alhazmy13","description":"A Serverless skeleton project using Python","archived":false,"fork":false,"pushed_at":"2021-09-27T07:07:48.000Z","size":290,"stargazers_count":41,"open_issues_count":5,"forks_count":2,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-05-01T15:29:05.509Z","etag":null,"topics":["aws","aws-lambda","python3","serverless"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alhazmy13.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-02T21:26:45.000Z","updated_at":"2024-05-01T15:29:05.510Z","dependencies_parsed_at":"2022-09-10T14:41:23.573Z","dependency_job_id":null,"html_url":"https://github.com/alhazmy13/aws-serverless-skeleton","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alhazmy13%2Faws-serverless-skeleton","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alhazmy13%2Faws-serverless-skeleton/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alhazmy13%2Faws-serverless-skeleton/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alhazmy13%2Faws-serverless-skeleton/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alhazmy13","download_url":"https://codeload.github.com/alhazmy13/aws-serverless-skeleton/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230212966,"owners_count":18191098,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-lambda","python3","serverless"],"created_at":"2024-12-18T03:25:55.620Z","updated_at":"2024-12-18T03:31:11.392Z","avatar_url":"https://github.com/alhazmy13.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n# Aws Serverless Skeleton \n\n![License](https://img.shields.io/badge/license-MIT-green.svg)\n[![Coverage Status](https://coveralls.io/repos/github/alhazmy13/aws-serverless-skeleton/badge.svg?branch=master)](https://coveralls.io/github/alhazmy13/aws-serverless-skeleton?branch=master)\n[![Build Status](https://travis-ci.com/alhazmy13/aws-serverless-skeleton.svg?branch=master)](https://travis-ci.com/alhazmy13/aws-serverless-skeleton)\n![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?longCache=true)\n![Python Versions](https://img.shields.io/badge/python-3.5%20%7C%203.6%20%7C%203.7-blue.svg)\n\n# Overview\n\n*Aws Serverless Skeleton* is built on top of AWS (Amazon Web Service) using multiple services :\n\n* **API Gateway** \n* **DynamoDB**\n* **DynamoDB Streams**\n* **S3**\n* **Lambda**\n* **Cognito**\n* **ES (Elasticsearch Service)**\n* **CloudFormation**\n* **CloudWatch**\n\n*Note*: This project may be edited directly in the browser using the gitpod application which is provides a full blown IDE.\n\n[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io#https://github.com/alhazmy13/aws-serverless-skeleton)\n\n## Contents\n\n* [Requirements](#requirements)\n* [Installing](#installing)\n* [Setup AWS](#setup-aws)\n* [Deploy to AWS](#deploy-to-aws)\n* [Run it locally](#run-it-locally)\n* [Trying the service with Postman](#trying-the-service-with-postman)\n* [Configuration](#configuration)\n    + [Authorization](#authorization)\n        + [Over lambda function](#over-lambda-function)\n        + [Over Cognito](#over-cognito)\n    + [Cognito](#cognito)\n    + [DynamoDB](#dynamodb)\n    + [ElasticSearch](#elastic-search)\n    + [S3](#s3)\n    + [VPC](#vpc)\n* [Structure](#structure)\n  + [Lambda Function](#lambda-function)\n  + [App Service](#app-service)\n* [Seeds](#seeds)\n* [Testing](#testing)\n\n\n## Requirements\n\n* `python` (Python 3.x)\n* `pip` (python package manager)\n* `npm` (node.js package manager)\n* `serverless` (serverless Framework ) https://github.com/serverless/serverless\n\n## Installing\nin order to start running the *Skeleton* on your AWS account you need to install some requirements before starting with : \n\ninstall *python3* is via `brew`:\n```\nbrew install python3\n```\n\ninstall *npm* is via `brew`:\n```\nbrew install node\n```\n\ninstall *serverless* is via `npm`:\n\n```\nnpm install -g serverless\n```\n\ninstall serverless plugins:\n\n```\ncd aws-serverless-skeleton (you have to be in the repo root directory)\nnpm install\n```\n\n## Setup AWS \nYou need to configure AWS with your own credentials. You need to install aws cli. In your python3 virtualenv, do:\n```\npip3 install awscli\n``` \nThen configure it:\n```\naws configure\n```\nyou will be asked to provide your AWS Access Key ID, AWS Secret Access Key and region (eu-west-1) and default output format (json).\nonce you are done, make sure the configuration is working:\n\n```\naws sts get-caller-identity\naws iam list-users --output table\n```\nif all is well, then you are good to go!\n\n## Deploy to AWS\nby simple command from terminal:\n\n```js\nnpm run deploy-dev\n// for prod env \nnpm run deploy-prod\n```\n\nalso you could deploy the function changed , Use this to quickly upload and overwrite your AWS Lambda code on AWS, allowing you to develop faster.\n\n```\nsls deploy function -f #function_name# --stage #stage_name#\n```\n\n## Run it locally\n\n* first of all you need to install all python and npm requirements:\n\n```\npip3 install -r requirements.txt\nnpm install\n```\n* Install dynamodb-local: \n\n```\nnpm run dynamo-install\n```\n\n* install elasticsearch:\n\nThe below command will install elastic search in ~/sources/\n\n```commandline\nnpm run elasticsearch-install\n```\n\n* Start serverless-offline, dynamodb-local and elasticsearch. Make sure above command is executed before this. \n\n```\nnpm run start\n```\n\nBy default you can send your requests to ```http://localhost:3000/``` or ```http://localhost:8000/shell``` to access the web shell for dynamodb-local or ```http://localhost:9200``` for elasticsearch.\n\n**Please note that:**\n\n* You'll need to restart the plugin if you modify your serverless.yml or any of the default  template files.\n* The event object passed to your λs has one extra key: { isOffline: true }. Also, process.env.IS_OFFLINE is true.\n* Seed config for dynamodb-local is enabled, that's mean each table will be seeded automatically on startup from JSON files. You can start the server with fresh table by this command: ``` npm run dynamo-start ```\n\n## Trying the service with Postman: \nTo install Postman, go to the apps page and click Download for Mac / Windows / Linux depending on your platform.\n[Download](https://www.getpostman.com/docs/postman/launching_postman/installation_and_updates)\n\nafter downloading *Postman* you need to add the collection of endpoint of the services to be called from [collections](https://raw.githubusercontent.com/alhazmy13/aws-serverless-skeleton/master/postman/aws-serverless-skeleton.postman_collection.json)\n\n1. from import button, choose import from url and paste the url above. \n2. right click on the collection \"posts\", choose edit, and then choose variables tab.\n3. add key = BASE_URL and value is either: *YOUR_BASE_URL* or [local](http://localhost:3000/)\n4. to run any of the requests, just select it and hit run ( to test, choose post and then \"get all posts\" )\n\n \n## Configuration\n\nYou will find a folder `config` that have a separate file for each environment (`dev`, `prod` and `local`) each file has \n* `environment` for environment values like DynamoDB table names or elastic search endpoint.\n* `custom` to modify and update the resource configuration, for example from `custom` you can change the elastic search instance type.\n* `functions` for a list of lambda function to deploy in environment.\n* `authorizer` For more information please [read this section](#authorization)  \n\n`resourse` folder that contains a bunch of files to deploy the required resources in the `CloudFormation` stack, you can enable or disable any resource from `serverless.yml` file.    \n\n### Authorization\n\n#### Over lambda function\n\nWe have a dummy function `AuthorizerService` to authorize the request, you can update it with any authorizer you like.\n \nFor this approach, you need to append below code in your env (`dev-env.yml` or `prod-env.yml`) file.\n\n```yaml\nauthorizer:\n  name: auth_authorizer\n  resultTtlInSeconds: 0\n  type: token\n```\n\n#### Over Cognito\n\nPlease read more about this in [Cognito Section](#cognito)\n\n\n### Cognito\n\nIn this skeleton, We are counting on Cognito with Authorization and Authentication process, and there are two ways to apply cognito.\n\n#### First approach\n\nSeparate cognito in a different stack or do it manually and then append `Pool ARN` to your environment.\nif you are following this approach then you need to update `POOL_ARN` value in your env file (`dev-env.yml` or `prod-env.yml`) with your user pool ARN like so:\n\n```yaml\nenvironment:\n  POOL_ARN: 'arn:aws:cognito-idp:{REGION}:{ACCOUNT_NUMBER}:userpool/{REGION}_{USER_POOL_ID}'\n\n```  \n\nAnd in your env file just change the `authorizer` to :\n\n```yaml\nauthorizer:\n  name: authorizer\n  arn: ${self:provider.environment.POOL_ARN}\n\n```\n\nAfter deploying the stack, just go to your user pool and enable `PostConfirmation` trigger with `auth_post` function. \n\n***NOTE*** make sure to remove cognito recourse form `serverless.yml` file.\n\n#### Second approach\n\nDeploying the user pool resource within the same stack by appending `${file(config/resource/cognito.yml)}` under `resources` in `serverless.yml` file.\n\n```yaml\nresources:\n  - ${file(config/resource/cognito.yml)}\n```\n\nGo to `lambda_functions/aut/functions.yml` and change:\n\n```yaml\nauth_post:\n  handler: lambda_functions/auth/auth.post_auth\n```\n\nTo:\n\n```yaml\nauth_post:\n  handler: lambda_functions/auth/auth.post_auth\n  events:\n    - cognitoUserPool:\n        pool:\n          Ref: CognitoUserPool\n        trigger: PostConfirmation\n ```\n\nIn your env file just change the `authorizer` to :\n\n```yaml\nauthorizer:\n  type: COGNITO_USER_POOLS\n  authorizerId:\n    Ref: ApiGatewayAuthorizer\n```\n\n### DynamoDB\n\nWorking on it. \n\n### Elastic Search\n\nWorking on it. \n\n### S3\n\nWorking on it.  \n\n### VPC\n\nWe assume that you already you have a VPC with in your AWS region, so there's no recourse to deploy a VPC with in the same stack however to deploy the lambda functions into a non-default VPC you need to update three values in (`dev-env.yml` or `prod-env.yml`) file.\n\n```yaml\nenvironment:\n  VPC_SECURITY_GROUP: \"VPC_SECURITY_GROUP\"\n  VPC_SUBNET_PUBLIC_1: \"VPC_SUBNET_PUBLIC_1\"\n  VPC_SUBNET_PUBLIC_2: \"VPC_SUBNET_PUBLIC_2\"\n```\n\n**NOTE** to deploy the lambda functions with default VPC just remove `vpc` value from `serverless.yml` file.\n\n```yaml\nprovider:\n  vpc:\n      securityGroupIds:\n        - ${self:provider.environment.VPC_SECURITY_GROUP}\n      subnetIds:\n        - ${self:provider.environment.VPC_SUBNET_PUBLIC_1}\n        - ${self:provider.environment.VPC_SUBNET_PUBLIC_2}\n```  \n\n## Structure\n\nIn this skeleton, you will find that we separate the lambda function handler from the business logic itself, for too many reasons.\n\n### Lambda Function\n\nIt contains a list of folders, each folder for only one route and each folder contains only two files.\n\n* `route_name.py` with a list of lambda function handler that returns the service response.\n* `functions.yml` with a list of lambda function recourse name and the configuration for each function, for example `events` type, `http` method or the `path` for the route.   \n\n### App Service\n\nThis folder (`src`) contains all our business logic\n* `app package` has a list of packages, each package has the name for the route with a list of services that represent our `CRUD` and `model` class\n* `common` contains a list of helper classes.\n\n## Seeds\n\nwe inject some seed data into our tables with local env, this helped us with test our application, to change the data just update any `json` file from `seed` folder.\n\n\n## Testing\n\nThe project contains a set of unit and integration tests but before all make sure you follow this [instruction](#installing) before run test commands.\n\nYou need to install `tox` tool:\n\n```\npip install -r requirements-dev.txt\n```\n\nMake sure all the services are ruining on your device:\n\n```\nnpm run start\n```\n\nTo install dev requirements and test this project against Python3.6, just type: \n \n```\ntox\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falhazmy13%2Faws-serverless-skeleton","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falhazmy13%2Faws-serverless-skeleton","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falhazmy13%2Faws-serverless-skeleton/lists"}