Skip to content
Simple flask boilerplate with Postgres, Docker, and Heroku/Zeit now
Branch: master
Clone or download
Latest commit 88b9077 Jun 13, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci Added circle ci Mar 21, 2019
api security update and linting Jun 13, 2019
docs fixed README to align with wiki for documentation + deleted old docs Jun 5, 2018
scripts moved docker scripts to script folder Mar 22, 2019
tests Added circle ci Mar 21, 2019
.dockerignore removed pipenv because of many annoying problems occur - will upgrade… Dec 25, 2018
.env docs and docker Dec 23, 2017
.gitignore added instructions to not hard code database creds and pegged versions Oct 17, 2018
Dockerfile removed pipenv because of many annoying problems occur - will upgrade… Dec 25, 2018
Dockerfile-dev removed pipenv because of many annoying problems occur - will upgrade… Dec 25, 2018
LICENSE docs and docker Dec 23, 2017
Makefile moved docker scripts to script folder Mar 22, 2019
Procfile added instructions to not hard code database creds and pegged versions Oct 17, 2018 Added new POST request example Mar 21, 2019
app.json Adding easy Heroku deployment Mar 21, 2019
docker-compose.yml moved docker scripts to script folder Mar 22, 2019 fixes mac setup script Feb 13, 2019
now.json removed pipenv because of many annoying problems occur - will upgrade… Dec 25, 2018
pytest.ini moved some deps to dev deps Jul 20, 2018
requirements-dev.txt removed pipenv because of many annoying problems occur - will upgrade… Dec 25, 2018
requirements.txt security update and linting Jun 13, 2019
runtime.txt heroku update for python runtime Dec 9, 2018

Flask Boilerplate CircleCI Code style: black

Deploy Deploy to now

This is an minimal but opinionated boilerplate meant for building out simple REST APIs. It is primarily used at Hack4Impact UIUC. This app is written in Python 3.6 with Postgres 10 as the chosen data persistence. The default way to deploy it is with Heroku or Zeit now but you can deploy it with another service, like AWS, Google Cloud, or DigitalOcean with Gunicorn and Nginx, but instructions for that are not provided. Included are simple examples and instructions developing with or without Docker are provided. I've also written a blog post about using Docker based on this repository.

Documentation is located here. We use black for code formatting, and mypy for optional static typing.


The goal of this boilerplate is to allow developers to quickly write their API with code structured to best practices while giving them flexibility to easily add/change features. Here are the problems this is trying to solve:

  1. Flask is too flexible. With Flask, you can write your application in any structure you like, even in one file. There are also a lot of different tutorials and guides providing different instructions & application structures to set up a Flask app with a database, confusing many newcomers about best practices.

  2. Django and other Flask boilerplates are too heavy. Sometimes, I don't need a fully featured admin portal with Redis and an Email manager nor do I need templates. Many APIs and applications require the use of a database though. Thus, I've chosen Postgres because it is a battle-tested and reliable database used in many companies and we know that 99% of applications can easily be designed to use relational databases (especially the ones used at Hack4Impact).


Please Please PLEASE read the documentation if you don't understand something relevant to this boilerplate. Documentation is provided in the wiki page of this repository. I've also added comments with links to specific Flask Documentation to explain certain design choices and/or a specific Flask API (ex: test clients).


Here are some quickstart instructions, although I would look at the documentation for more details and other options of setting up your environment (e.g. full Docker setup, installed postgres instance, pipenv, etc).

First start a postgres docker container and persist the data with a volume flask-app-db:

make start_dev_db

Another option is to create a postgres instance on a cloud service like elephantsql and connect it to this app. Remember to change the postgres url and don't hard code it in!

Then, start your virtual environment

$ pip3 install virtualenv
$ virtualenv venv
$ source venv/bin/activate

Now, install the python dependencies and run the server:

(venv) $ pip install -r requirements.txt
(venv) $ pip install -r requirements-dev.txt
(venv) $ python recreate_db
(venv) $ python runserver

To exit the virtual environment:

(venv) $ deactivate

For ease of setup, I have hard-coded postgres URLs for development and docker configurations. If you are using a separate postgres instance as mentioned above, do not hardcode the postgres url including the credentials to your code. Instead, create a file called creds.ini in the same directory level as and write something like this:

pg_url = postgresql://testusr:password@

Note: you will need to call api.core.get_pg_url in the Config file.

For production, you should do something similar with the flask SECRET_KEY.

Easier setup

I've created a makefile to make this entire process easier but purposely provided verbose instructions there to show you what is necessary to start this application. To do so:

$ make setup

If you like to destroy your docker postgres database and start over, run:

$ make recreate_db

This is under the assumption that you have only set up one postgres container that's linked to the flask-app-db volume.

I would highly suggest reading the documentation for more details on setup.


You may use Heroku or Zeit Now and the instructions are defined in the wiki page. I would recommend Heroku. The easiest way to do so is to click the Heroku Deploy button. Remember, once you fork/copy this repo, you will need to change app.json, especially the repository key. Everything else should be fine.

Repository Contents

  • api/views/ - Holds files that define your endpoints
  • api/models/ - Holds files that defines your database schema
  • api/ - What is initially ran when you start your application
  • api/ - utility functions and classes - explained here
  • api/ - includes core functionality including error handlers and logger
  • api/ - app reference for gunicorn
  • tests/ - Folder holding tests


  • - Provides Configuration for the application. There are two configurations: one for development and one for production using Heroku.
  • - Command line interface that allows you to perform common functions with a command
  • requirements.txt - A list of python package dependencies the application requires
  • runtime.txt & Procfile - configuration for Heroku
  • Dockerfile - instructions for Docker to build the Flask app
  • docker-compose.yml - config to setup this Flask app and a Database
  • migrations/ - Holds migration files – doesn't exist until you python db init if you decide to not use docker


If you're annoyed by the pycache files

find . | grep -E "(__pycache__|\.pyc|\.pyo$)" | xargs rm -rf

Additional Documentation

Feel free to contact me for questions and contributions are welcome :)

You can’t perform that action at this time.