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
- Conventions
- Database Interactions & Troubleshooting
- Heroku Deployment
- Docker
- Windows subsystem for Linux setup
- Regular setup if you hate Docker
Repository Contents
api/views/
- Holds files that define your endpointsapi/models.py
- Defines your database schemaapi/__init__.py
- What is initially ran when you start your applicationtests/
- 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 commandrequirements.txt
- A list of python package dependencies the application requiresruntime.txt
&Procfile
- configuration for HerokuDockerfile
- instructions for Docker to build the Flask appdocker-compose.yml
- config to setup this Flask app and a Databasepostgres-data/
- Postgres Docker Container data - doesnt exist until you build your docker images and start your containersmigrations/
- Holds migration files – doesn't exist until youpython 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 Applicationpostgres
: 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
postgres-data
will be created. DO NOT DELETE IT!! It holds all your data in your database.
Note: A new directory called 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
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
.
NOTE: Be careful to not run multiple containers of the same image. Check with 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
- Flask - Flask Documentation
- Flask SQLAlchemy - the ORM for the database
- Heroku - Deployment using Heroku
- Learn Python - Learning Python3
- Relational Databases - Designing a database schema
- REST API - tips on making an API Restful
- Docker Docs - Docker docs
Feel free to contact me for questions :)
tk2@illinois.edu