Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Cookiecutter for Flask API


Reusable template to quickly run your Flask API with or without a Database. It supports DynamoDB for now.

Software design

Software Design

Software design is based on Clean Architecture from this post. Goal of the design is to make use of repositories and models so that it can conveniently switch data sources.

Supported options

  • Flask API only (without repositories and models)
  • Flask API with DynamoDB

Getting Started

  1. Install cookiecutter.

  2. Run the following command:

  3. Follow the instructions in the command line.


Run with Docker


  • Install Docker

Run the following command:

docker-compose up

After running docker compose, you might see the following:

pynamodb.exceptions.TableError: Unable to describe table: Could not connect to the endpoint URL: "http://db:8000/"

This is because Flask is trying to connect to DynamoDB while the table is not yet available. This can be ignored because Flask will retry to connect after failure.

Local endpoints:

Run locally



Skip the steps that you don't need.

  1. Run the local DynamoDB
    java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar
  2. Setup your virtual environment. Guide here.
  3. Install the required packages:
    pip install -r requirements.txt
  4. Populate the DynamoDB table.
    FLASK_ENV=development FLASK_APP=app/ flask dynamo create-poem-table
  5. Run Flask locally:
    FLASK_ENV=development FLASK_APP=app/ FLASK_DEBUG=1 flask run 

Testing locally

Checkout this repo and Run the following:

cookiecutter cookiecutter-flask-dynamodb

Production build

Run with gunicorn.

FLASK_ENV=production gunicorn AWS_ACCESS_KEY_ID="your-key-here" --build-arg AWS_SECRET_ACCESS_KEY="your-key-here" --bind wsgi

Build with docker for production.

docker build . -f --build-arg FLASK_ENV="production" --build-arg AWS_ACCESS_KEY_ID="your-key-here" --build-arg AWS_SECRET_ACCESS_KEY="your-key-here" -t production_image_build