/flask-boilerplate

Simple flask boilerplate with Docker and Heroku

Primary LanguagePythonMIT LicenseMIT

Flask Boilerplate

This Boilerplate is meant for building out simple REST APIs deployed using Heroku and developed using Docker containers. This app is written in Python 3.6 with Postgres 10 as the chosen data persistance. You can deploy it with another service, like AWS, Google Cloud, and DigitalOcean with Gunicorn and Nginx, but instructions for that are not provided. Included are simple examples to help you get started. For development, the default way is to use Docker for ease of setup. However, there is documentation for setup without docker here. I've also written a blog post about using Docker based on this repository.

Docs

Please Please PLEASE read documentation if you dont understand something

Repository Contents

  • api/views/ - Holds files that define your endpoints
  • api/models.py - Defines your database schema
  • api/__init__.py - What is initially ran when you start your application
  • tests/ - Folder holding tests

Others

  • config.py - Provides Configuration for the application. There are two configurations: one for development and one for production using Heroku.
  • manage.py - 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
  • postgres-data/ - Postgres Docker Container data - doesnt exist until you build your docker images and start your containers
  • migrations/ - Holds migration files – doesn't exist until you python manage.py db init if you decide to not use docker

Prereqs

We will be utilizing Docker to provide the same development environment across your team. This will eliminate aggravating environment troubleshooting in different Operating Systems. We will not be using Docker in production since deployment using Heroku is easier. Check out this blog post I wrote for more information.

  • Docker – if you are running Linux, install the Server version and install Docker-Compose. And that's it! For Mac, you will see a Docker icon on the top bar, indicating that docker is running.

Our Docker Configuration

We have two Docker Images:

  • app: Our Flask Application
  • postgres: Postgres Database

Setup

First, clone the repo:

git clone https://github.com/tko22/flask-boilerplate.git

Check if you have installed Docker and Docker-Compose(Installing Docker on Mac/Windows will automatically install Docker-Compose):

$ docker -v
Docker version 17.09.1-ce, build 19e2cf6
$ docker-compose -v
docker-compose version 1.17.1, build 6d101fb

If it doesn't work, try resetting your shell:

$ reset

Now build the Docker images(the flask app and postgres database) and setup the database:

$ docker-compose build
$ docker-compose up -d
$ docker-compose exec app python manage.py recreate_db

Check if your Docker Containers are running:

$ docker ps

Now go to http://localhost:5000/ and you should see the app running! Since it is in development configurations, any changes in your code will appear in the container and will auto-reload just like it would normally. docker-compose up -d will build and start it. You will not be using that to start the container after this setup step. Look at the next section for instructions.
Now stop the container:

$ docker-compose stop

Note: A new directory called postgres-data will be created. DO NOT DELETE IT!! It holds all your data in your database.

Running and Stopping Docker Containers - these are the instructions you run after the Setup!

To start your Postgres and your flask api:

$ docker-compose start

To stop them:

$ docker-compose stop

To view your logs for the api:

$ docker-compose logs app

If you need to rebuild your containers, delete the previous containers and rebuild

$ docker-compose rm -f
$ docker-compose up -d

NOTE: Be careful to not run multiple containers of the same image. Check with docker ps and use docker-compose stop to stop all the containers if you are running multiple containers and then restart with docker-compose start.

MISC

If you would prefer to setup your application environment instead of using Docker, follow this doc - Regular Setup 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 :)
tk2@illinois.edu