diff --git a/docker-compose.sam.yml b/docker-compose.sam.yml new file mode 100644 index 0000000..a31e10b --- /dev/null +++ b/docker-compose.sam.yml @@ -0,0 +1,12 @@ +version: '3.7' +services: + sam-local: + build: ./sam-local + container_name: sam-local + privileged: true + ports: + - "3000:3000" + env_file: + .env + volumes: + - ./sam-local:/app diff --git a/docker-compose.yml b/docker-compose.yml index 8931def..f33d337 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,4 +1,4 @@ -version: '3' +version: '3.7' services: # -------------------------------------------------------------------------- # FRONTEND WRITTEN IN ANGULAR diff --git a/sam-local/Dockerfile b/sam-local/Dockerfile new file mode 100644 index 0000000..ff9c698 --- /dev/null +++ b/sam-local/Dockerfile @@ -0,0 +1,12 @@ +FROM docker:dind +RUN apk add --update \ + python \ + python-dev \ + py-pip \ + build-base \ + && pip install virtualenv \ + && rm -rf /var/cache/apk/* +RUN pip install --user aws-sam-cli +ENV PATH=$PATH:/root/.local/bin +RUN mkdir /app +WORKDIR /app diff --git a/sam-local/sam-app/.gitignore b/sam-local/sam-app/.gitignore new file mode 100644 index 0000000..4808264 --- /dev/null +++ b/sam-local/sam-app/.gitignore @@ -0,0 +1,244 @@ + +# Created by https://www.gitignore.io/api/osx,linux,python,windows,pycharm,visualstudiocode + +### Linux ### +*~ + +# temporary files which can be created if a process still has a handle open of a deleted file +.fuse_hidden* + +# KDE directory preferences +.directory + +# Linux trash folder which might appear on any partition or disk +.Trash-* + +# .nfs files are created when an open file is removed but is still being accessed +.nfs* + +### OSX ### +*.DS_Store +.AppleDouble +.LSOverride + +# Icon must end with two \r +Icon + +# Thumbnails +._* + +# Files that might appear in the root of a volume +.DocumentRevisions-V100 +.fseventsd +.Spotlight-V100 +.TemporaryItems +.Trashes +.VolumeIcon.icns +.com.apple.timemachine.donotpresent + +# Directories potentially created on remote AFP share +.AppleDB +.AppleDesktop +Network Trash Folder +Temporary Items +.apdisk + +### PyCharm ### +# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm +# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 + +# User-specific stuff: +.idea/**/workspace.xml +.idea/**/tasks.xml +.idea/dictionaries + +# Sensitive or high-churn files: +.idea/**/dataSources/ +.idea/**/dataSources.ids +.idea/**/dataSources.xml +.idea/**/dataSources.local.xml +.idea/**/sqlDataSources.xml +.idea/**/dynamic.xml +.idea/**/uiDesigner.xml + +# Gradle: +.idea/**/gradle.xml +.idea/**/libraries + +# CMake +cmake-build-debug/ + +# Mongo Explorer plugin: +.idea/**/mongoSettings.xml + +## File-based project format: +*.iws + +## Plugin-specific files: + +# IntelliJ +/out/ + +# mpeltonen/sbt-idea plugin +.idea_modules/ + +# JIRA plugin +atlassian-ide-plugin.xml + +# Cursive Clojure plugin +.idea/replstate.xml + +# Ruby plugin and RubyMine +/.rakeTasks + +# Crashlytics plugin (for Android Studio and IntelliJ) +com_crashlytics_export_strings.xml +crashlytics.properties +crashlytics-build.properties +fabric.properties + +### PyCharm Patch ### +# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721 + +# *.iml +# modules.xml +# .idea/misc.xml +# *.ipr + +# Sonarlint plugin +.idea/sonarlint + +### Python ### +# Byte-compiled / optimized / DLL files +__pycache__/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python +build/ +develop-eggs/ +dist/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +*.egg-info/ +.installed.cfg +*.egg + +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.coverage +.coverage.* +.cache +.pytest_cache/ +nosetests.xml +coverage.xml +*.cover +.hypothesis/ + +# Translations +*.mo +*.pot + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# pyenv +.python-version + +# celery beat schedule file +celerybeat-schedule.* + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ + +### VisualStudioCode ### +.vscode/* +!.vscode/settings.json +!.vscode/tasks.json +!.vscode/launch.json +!.vscode/extensions.json +.history + +### Windows ### +# Windows thumbnail cache files +Thumbs.db +ehthumbs.db +ehthumbs_vista.db + +# Folder config file +Desktop.ini + +# Recycle Bin used on file shares +$RECYCLE.BIN/ + +# Windows Installer files +*.cab +*.msi +*.msm +*.msp + +# Windows shortcuts +*.lnk + +# Build folder + +*/build/* + +# End of https://www.gitignore.io/api/osx,linux,python,windows,pycharm,visualstudiocode \ No newline at end of file diff --git a/sam-local/sam-app/README.md b/sam-local/sam-app/README.md new file mode 100644 index 0000000..a42c803 --- /dev/null +++ b/sam-local/sam-app/README.md @@ -0,0 +1,210 @@ +# sam-app + +This is a sample template for sam-app - Below is a brief explanation of what we have generated for you: + +```bash +. +├── README.md <-- This instructions file +├── event.json <-- API Gateway Proxy Integration event payload +├── hello_world <-- Source code for a lambda function +│   ├── __init__.py +│   ├── app.py <-- Lambda function code +│   ├── requirements.txt <-- Lambda function code +├── template.yaml <-- SAM Template +└── tests <-- Unit tests + └── unit + ├── __init__.py + └── test_handler.py +``` + +## Requirements + +* AWS CLI already configured with Administrator permission +* [Python 3 installed](https://www.python.org/downloads/) +* [Docker installed](https://www.docker.com/community-edition) + +## Setup process + +### Local development + +**Invoking function locally using a local sample payload** + +```bash +sam local invoke HelloWorldFunction --event event.json +``` + +**Invoking function locally through local API Gateway** + +```bash +sam local start-api +``` + +If the previous command ran successfully you should now be able to hit the following local endpoint to invoke your function `http://localhost:3000/hello` + +**SAM CLI** is used to emulate both Lambda and API Gateway locally and uses our `template.yaml` to understand how to bootstrap this environment (runtime, where the source code is, etc.) - The following excerpt is what the CLI will read in order to initialize an API and its routes: + +```yaml +... +Events: + HelloWorld: + Type: Api # More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api + Properties: + Path: /hello + Method: get +``` + +## Packaging and deployment + +AWS Lambda Python runtime requires a flat folder with all dependencies including the application. SAM will use `CodeUri` property to know where to look up for both application and dependencies: + +```yaml +... + HelloWorldFunction: + Type: AWS::Serverless::Function + Properties: + CodeUri: hello_world/ + ... +``` + +Firstly, we need a `S3 bucket` where we can upload our Lambda functions packaged as ZIP before we deploy anything - If you don't have a S3 bucket to store code artifacts then this is a good time to create one: + +```bash +aws s3 mb s3://BUCKET_NAME +``` + +Next, run the following command to package our Lambda function to S3: + +```bash +sam package \ + --output-template-file packaged.yaml \ + --s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME +``` + +Next, the following command will create a Cloudformation Stack and deploy your SAM resources. + +```bash +sam deploy \ + --template-file packaged.yaml \ + --stack-name sam-app \ + --capabilities CAPABILITY_IAM +``` + +> **See [Serverless Application Model (SAM) HOWTO Guide](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-quick-start.html) for more details in how to get started.** + +After deployment is complete you can run the following command to retrieve the API Gateway Endpoint URL: + +```bash +aws cloudformation describe-stacks \ + --stack-name sam-app \ + --query 'Stacks[].Outputs[?OutputKey==`HelloWorldApi`]' \ + --output table +``` + +## Fetch, tail, and filter Lambda function logs + +To simplify troubleshooting, SAM CLI has a command called sam logs. sam logs lets you fetch logs generated by your Lambda function from the command line. In addition to printing the logs on the terminal, this command has several nifty features to help you quickly find the bug. + +`NOTE`: This command works for all AWS Lambda functions; not just the ones you deploy using SAM. + +```bash +sam logs -n HelloWorldFunction --stack-name sam-app --tail +``` + +You can find more information and examples about filtering Lambda function logs in the [SAM CLI Documentation](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-logging.html). + +## Testing + + +Next, we install test dependencies and we run `pytest` against our `tests` folder to run our initial unit tests: + +```bash +pip install pytest pytest-mock --user +python -m pytest tests/ -v +``` + +## Cleanup + +In order to delete our Serverless Application recently deployed you can use the following AWS CLI Command: + +```bash +aws cloudformation delete-stack --stack-name sam-app +``` + +## Bringing to the next level + +Here are a few things you can try to get more acquainted with building serverless applications using SAM: + +### Learn how SAM Build can help you with dependencies + +* Uncomment lines on `app.py` +* Build the project with ``sam build --use-container`` +* Invoke with ``sam local invoke HelloWorldFunction --event event.json`` +* Update tests + +### Create an additional API resource + +* Create a catch all resource (e.g. /hello/{proxy+}) and return the name requested through this new path +* Update tests + +### Step-through debugging + +* **[Enable step-through debugging docs for supported runtimes]((https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-debugging.html))** + +Next, you can use AWS Serverless Application Repository to deploy ready to use Apps that go beyond hello world samples and learn how authors developed their applications: [AWS Serverless Application Repository main page](https://aws.amazon.com/serverless/serverlessrepo/) + +# Appendix + +## Building the project + +[AWS Lambda requires a flat folder](https://docs.aws.amazon.com/lambda/latest/dg/lambda-python-how-to-create-deployment-package.html) with the application as well as its dependencies in deployment package. When you make changes to your source code or dependency manifest, +run the following command to build your project local testing and deployment: + +```bash +sam build +``` + +If your dependencies contain native modules that need to be compiled specifically for the operating system running on AWS Lambda, use this command to build inside a Lambda-like Docker container instead: +```bash +sam build --use-container +``` + +By default, this command writes built artifacts to `.aws-sam/build` folder. + +## SAM and AWS CLI commands + +All commands used throughout this document + +```bash +# Generate event.json via generate-event command +sam local generate-event apigateway aws-proxy > event.json + +# Invoke function locally with event.json as an input +sam local invoke HelloWorldFunction --event event.json + +# Run API Gateway locally +sam local start-api + +# Create S3 bucket +aws s3 mb s3://BUCKET_NAME + +# Package Lambda function defined locally and upload to S3 as an artifact +sam package \ + --output-template-file packaged.yaml \ + --s3-bucket REPLACE_THIS_WITH_YOUR_S3_BUCKET_NAME + +# Deploy SAM template as a CloudFormation stack +sam deploy \ + --template-file packaged.yaml \ + --stack-name sam-app \ + --capabilities CAPABILITY_IAM + +# Describe Output section of CloudFormation stack previously created +aws cloudformation describe-stacks \ + --stack-name sam-app \ + --query 'Stacks[].Outputs[?OutputKey==`HelloWorldApi`]' \ + --output table + +# Tail Lambda function Logs using Logical name defined in SAM Template +sam logs -n HelloWorldFunction --stack-name sam-app --tail +``` + diff --git a/sam-local/sam-app/event.json b/sam-local/sam-app/event.json new file mode 100644 index 0000000..070ad8e --- /dev/null +++ b/sam-local/sam-app/event.json @@ -0,0 +1,62 @@ +{ + "body": "{\"message\": \"hello world\"}", + "resource": "/{proxy+}", + "path": "/path/to/resource", + "httpMethod": "POST", + "isBase64Encoded": false, + "queryStringParameters": { + "foo": "bar" + }, + "pathParameters": { + "proxy": "/path/to/resource" + }, + "stageVariables": { + "baz": "qux" + }, + "headers": { + "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8", + "Accept-Encoding": "gzip, deflate, sdch", + "Accept-Language": "en-US,en;q=0.8", + "Cache-Control": "max-age=0", + "CloudFront-Forwarded-Proto": "https", + "CloudFront-Is-Desktop-Viewer": "true", + "CloudFront-Is-Mobile-Viewer": "false", + "CloudFront-Is-SmartTV-Viewer": "false", + "CloudFront-Is-Tablet-Viewer": "false", + "CloudFront-Viewer-Country": "US", + "Host": "1234567890.execute-api.us-east-1.amazonaws.com", + "Upgrade-Insecure-Requests": "1", + "User-Agent": "Custom User Agent String", + "Via": "1.1 08f323deadbeefa7af34d5feb414ce27.cloudfront.net (CloudFront)", + "X-Amz-Cf-Id": "cDehVQoZnx43VYQb9j2-nvCh-9z396Uhbp027Y2JvkCPNLmGJHqlaA==", + "X-Forwarded-For": "127.0.0.1, 127.0.0.2", + "X-Forwarded-Port": "443", + "X-Forwarded-Proto": "https" + }, + "requestContext": { + "accountId": "123456789012", + "resourceId": "123456", + "stage": "prod", + "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef", + "requestTime": "09/Apr/2015:12:34:56 +0000", + "requestTimeEpoch": 1428582896000, + "identity": { + "cognitoIdentityPoolId": null, + "accountId": null, + "cognitoIdentityId": null, + "caller": null, + "accessKey": null, + "sourceIp": "127.0.0.1", + "cognitoAuthenticationType": null, + "cognitoAuthenticationProvider": null, + "userArn": null, + "userAgent": "Custom User Agent String", + "user": null + }, + "path": "/prod/path/to/resource", + "resourcePath": "/{proxy+}", + "httpMethod": "POST", + "apiId": "1234567890", + "protocol": "HTTP/1.1" + } +} diff --git a/sam-local/sam-app/hello_world/__init__.py b/sam-local/sam-app/hello_world/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/sam-local/sam-app/hello_world/app.py b/sam-local/sam-app/hello_world/app.py new file mode 100644 index 0000000..0930620 --- /dev/null +++ b/sam-local/sam-app/hello_world/app.py @@ -0,0 +1,42 @@ +import json + +# import requests + + +def lambda_handler(event, context): + """Sample pure Lambda function + + Parameters + ---------- + event: dict, required + API Gateway Lambda Proxy Input Format + + Event doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html#api-gateway-simple-proxy-for-lambda-input-format + + context: object, required + Lambda Context runtime methods and attributes + + Context doc: https://docs.aws.amazon.com/lambda/latest/dg/python-context-object.html + + Returns + ------ + API Gateway Lambda Proxy Output Format: dict + + Return doc: https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-lambda-proxy-integrations.html + """ + + # try: + # ip = requests.get("http://checkip.amazonaws.com/") + # except requests.RequestException as e: + # # Send some context about this error to Lambda Logs + # print(e) + + # raise e + + return { + "statusCode": 200, + "body": json.dumps({ + "message": "hello world", + # "location": ip.text.replace("\n", "") + }), + } diff --git a/sam-local/sam-app/hello_world/requirements.txt b/sam-local/sam-app/hello_world/requirements.txt new file mode 100644 index 0000000..663bd1f --- /dev/null +++ b/sam-local/sam-app/hello_world/requirements.txt @@ -0,0 +1 @@ +requests \ No newline at end of file diff --git a/sam-local/sam-app/template.yaml b/sam-local/sam-app/template.yaml new file mode 100644 index 0000000..ab96a33 --- /dev/null +++ b/sam-local/sam-app/template.yaml @@ -0,0 +1,39 @@ +AWSTemplateFormatVersion: '2010-09-09' +Transform: AWS::Serverless-2016-10-31 +Description: > + sam-app + + Sample SAM Template for sam-app + +# More info about Globals: https://github.com/awslabs/serverless-application-model/blob/master/docs/globals.rst +Globals: + Function: + Timeout: 3 + +Resources: + HelloWorldFunction: + Type: AWS::Serverless::Function # More info about Function Resource: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#awsserverlessfunction + Properties: + CodeUri: hello_world/ + Handler: app.lambda_handler + Runtime: python3.7 + Events: + HelloWorld: + Type: Api # More info about API Event Source: https://github.com/awslabs/serverless-application-model/blob/master/versions/2016-10-31.md#api + Properties: + Path: /hello + Method: get + +Outputs: + # ServerlessRestApi is an implicit API created out of Events key under Serverless::Function + # Find out more about other implicit resources you can reference within SAM + # https://github.com/awslabs/serverless-application-model/blob/master/docs/internals/generated_resources.rst#api + HelloWorldApi: + Description: "API Gateway endpoint URL for Prod stage for Hello World function" + Value: !Sub "https://${ServerlessRestApi}.execute-api.${AWS::Region}.amazonaws.com/Prod/hello/" + HelloWorldFunction: + Description: "Hello World Lambda Function ARN" + Value: !GetAtt HelloWorldFunction.Arn + HelloWorldFunctionIamRole: + Description: "Implicit IAM Role created for Hello World function" + Value: !GetAtt HelloWorldFunctionRole.Arn diff --git a/sam-local/sam-app/tests/unit/__init__.py b/sam-local/sam-app/tests/unit/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/sam-local/sam-app/tests/unit/test_handler.py b/sam-local/sam-app/tests/unit/test_handler.py new file mode 100644 index 0000000..09588d3 --- /dev/null +++ b/sam-local/sam-app/tests/unit/test_handler.py @@ -0,0 +1,73 @@ +import json + +import pytest + +from hello_world import app + + +@pytest.fixture() +def apigw_event(): + """ Generates API GW Event""" + + return { + "body": '{ "test": "body"}', + "resource": "/{proxy+}", + "requestContext": { + "resourceId": "123456", + "apiId": "1234567890", + "resourcePath": "/{proxy+}", + "httpMethod": "POST", + "requestId": "c6af9ac6-7b61-11e6-9a41-93e8deadbeef", + "accountId": "123456789012", + "identity": { + "apiKey": "", + "userArn": "", + "cognitoAuthenticationType": "", + "caller": "", + "userAgent": "Custom User Agent String", + "user": "", + "cognitoIdentityPoolId": "", + "cognitoIdentityId": "", + "cognitoAuthenticationProvider": "", + "sourceIp": "127.0.0.1", + "accountId": "", + }, + "stage": "prod", + }, + "queryStringParameters": {"foo": "bar"}, + "headers": { + "Via": "1.1 08f323deadbeefa7af34d5feb414ce27.cloudfront.net (CloudFront)", + "Accept-Language": "en-US,en;q=0.8", + "CloudFront-Is-Desktop-Viewer": "true", + "CloudFront-Is-SmartTV-Viewer": "false", + "CloudFront-Is-Mobile-Viewer": "false", + "X-Forwarded-For": "127.0.0.1, 127.0.0.2", + "CloudFront-Viewer-Country": "US", + "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8", + "Upgrade-Insecure-Requests": "1", + "X-Forwarded-Port": "443", + "Host": "1234567890.execute-api.us-east-1.amazonaws.com", + "X-Forwarded-Proto": "https", + "X-Amz-Cf-Id": "aaaaaaaaaae3VYQb9jd-nvCd-de396Uhbp027Y2JvkCPNLmGJHqlaA==", + "CloudFront-Is-Tablet-Viewer": "false", + "Cache-Control": "max-age=0", + "User-Agent": "Custom User Agent String", + "CloudFront-Forwarded-Proto": "https", + "Accept-Encoding": "gzip, deflate, sdch", + }, + "pathParameters": {"proxy": "/examplepath"}, + "httpMethod": "POST", + "stageVariables": {"baz": "qux"}, + "path": "/examplepath", + } + + +def test_lambda_handler(apigw_event, mocker): + + ret = app.lambda_handler(apigw_event, "") + data = json.loads(ret["body"]) + + assert ret["statusCode"] == 200 + assert "message" in ret["body"] + assert data["message"] == "hello world" + # assert "location" in data.dict_keys()