jlhood / cookiecutter-python-sam

My personal opinionated way to structure python-based SAM apps

cookiecutter-python-sam

In the same spirit as cookiecutter-aws-sam-python, but with a lot more opinions and therefore a lot less options. 😊 This is my personal, opinionated way of structuring python-based SAM apps.

Features/Opinions

1. Lambda functions use python 3.8.
2. Lambda functions have X-Ray enabled.
3. pipenv is used for dependency management.
4. VS Code is used for editing.
5. flake8 and pydocstyle static analysis checks are run on Lambda function code.
6. Lambda function code is unit tested with an enforced code line coverage minimum (85%).
7. cfn-lint is run to validate the SAM template.
8. Lambda functions support runtime-configurable log level via template parameters and environment variables.
9. SAM CLI is used for build/package/local test/deploy/publish.
10. App is published to the AWS Serverless Application Repository (SAR).
11. Makefile is included with the following targets:
    1. clean - remove build artifacts.
    2. bootstrap - run once after initializing from cookiecutter to lock and install dependencies.
    3. init - used by CI build to install pre-requisites and locked dependencies.
    4. compile - run linters on python code and SAM template, run sam build.
    5. build - default target. Executes compile target.
    6. package - packages dependencies and uploads to S3, outputting a packaged template for deployment.
    7. publish - create/update corresponding app in AWS SAR.

Using the cookiecutter template

NOTE: This template assumes you have SAM CLI installed and the sam command is on your path. SAM CLI installation instructions can be found here.

Here's my flow for starting a new SAM app. Note, I use a Macbook and have not tested this template on anything else. Theoretically, it should work on any *nix OS, maybe with minor tweaks.

1. Create a new repository in GitHub.
   1. For the sake of this example, let's say you decided to name it my-sam-app.
   2. Do NOT have GitHub automatically create any files, e.g., README, etc.
2. cd to your workspace.
3. sam init --location gh:jlhood/cookiecutter-python-sam
   1. When prompted for project name, enter the name of your GitHub repo, e.g., my-sam-app.
   2. Choose 'y' for push_to_github.
   3. Answer remaining questions.
4. The cookiecutter template will automatically
   1. initialize the app from the template
   2. bootstrap dependencies
   3. initialize git and commit the app template changes
   4. push the changes to the GitHub remote repo
5. Add LICENSE file through GitHub UI
   1. Click "Create new file"
   2. Name the new file LICENSE
   3. Click "Choose a license template"
   4. Follow the steps to create and commit the LICENSE file from a template

Now you're ready to start making changes and testing using sam local:

1. make
2. sam local invoke --no-event

or deploy it like this:

1. PACKAGE_BUCKET=my-bucket make package
2. sam deploy --template-file .aws-sam/packaged-template.yml --stack-name my-stack --capabilities CAPABILITY_IAM

CI Setup

I like to setup CI via AWS CodeBuild for my SAM apps to ensure all PRs can be packaged and built successfully before merging them to master. If you use this cookiecutter template, setting up CI is simple, because I've published an app to the AWS Serverless Application Repository (SAR) that creates a CI CodeBuild project specifically designed to work out of the box with this cookiecutter template. To install, go to the app's SAR page and follow the instructions in the README.

License Summary

This sample code is made available under the MIT license. See the LICENSE file.