Awesome
flask-template
Introduction
Flask is one of the popular web development frameworks available within the Python domain alongside with others such as Django and Tornado. I personally prefer it over the others because it offers a minimalist approach. It comes with very basic wrappers and helper packages, and you can chose to install specific bits of the puzzle as you develop your project and figure out what you need.
Recently, Flask's developer, Miguel Grinberg, released a github project where he showcased a very useful way to structure flask based web applications. The project is flasky.
I was influenced by flasky, and wanted to create and share a template based on flask which can be used for quickly creating flask applications. I made some minor changes to the original flasky's project structure, and also decided to use a different database and docker setup, which in my opinion, is more oriented towards commercial web development.
I created a very basic short stories web application, which is more of a template rather than a proper full on web application. It allows users to create, view and edit short stories through an API and also through a very basic HTML based web page.
The following guide provides insights on how the bits and pieces of the project work, and hopefully is not too complicated so that even a beginner python developer can follow it.
Project Setup
First Steps
You can begin by either downloading a zip file of the project through github, or using a git command to clone the project by:
git clone https://github.com/alisezer/flask-template.git
Virtual Environment Setup
It is preferred to create a virtual environment per project, rather then installing all dependencies of each of your projects system wide. Once you install virtual env, and move to your projects directory through your terminal, you can set up a virtual env with:
virtualenv venv -p python3.6
This will create a python3.6 based virtual environment (venv) for you within your projects directory.
Note: You need to have Python 3.6 installed on your local device.
Dependency installations
To install the necessary packages:
source venv/bin/activate
pip install -r requirements.txt
This will install the required packages within your venv.
The Makefile
When you are in the project directory on your terminal, you can use the make
command for various options such as generating a new requirements.txt
file, installing requirements on your venv or cleaning old compiled python .pyc
files.
Try it out by entering the make
command, which will show you available options.
.ENV File
The .env file holds your project specific settings such as your DB host name. These settings are better kept secret in most cases, therefore .env file is never committed to git. You will need to create a .env file, which can easily be created using the .env.template
. Just run a simple copying command:
cp .env.template .env
and your .env file should be ready to be configured.
Variables in the .env file and their meanings:
- ENV: The config you want to use while setting up your app.
- CLIENT_LOGGER: Your client logger level
- FILE_LOGGER: Your file logger level
- Database configurations: these are used for configuring your postgres database
- SECRET_KEY: Flask's secret key which is used for hashing and security purposes. Make sure to keep this secret and don't commit to github.
The configurations are carried to code through the decouple
library, which IMO provides a better solution compared to the traditional python-dotenv
library.
Project Structure
Main Modules
Every flask application has a top-level module for creating the app itself, in this case, this module is the stories.py
. This contains the flask application, and is used by other services such as Gunicorn or Flask's CLI while serving the application.
The stories.py
module relies on the config.py
and the app/__init__.py
modules. It uses one of the configs specified in the .env
file to create an application through the create_app
method, which is placed under the __init__.py
module.
app/__init__.py
ties the necessary packages such as your SQLAlchemy or Migrations wrappers to your app, and provides a nice function for generating an application with a pre-specified config.
config.py
hold multiple configuration files, which can be used in different scenarios such as testing vs production.
Models
The models, which are your database objects, are handled through SQLAlchemy's ORM. Flask provides a wrapper around the traditional SQLAlchemy package, which is used through out this project.
The models created are similar to your regular Python classes. They are inherited from pre-specified SQLAlchemy classes to make database table creation processes easier. These models can be found under the app/models
folder.
In some projects, models can be handled within only one module, however in my opinion, it makes things easier when you handle them in multiple modules (one module per model).
If you want to create more models in your application, you can simply create modules under this folder, and later on tie them back to your app.
API
The project creates a simple API which has 4 endpoints for retrieving, creating and editing stories. The API is structured by using Flask's blueprint
functionality.
api/stories.py
module creates the endpoints, where the api/__init__.py
creates the blueprint for API formation.
The blueprint object is later on imported and tied to the app in the app/__init__.py
module.
Main APP (Web Page)
The project also creates a very simple web page for viewing and creating stories. The flow for this logic is handled under the app/main
folder. forms.py
basically creates a very simple web form for creating a story, while the views are handled in the views.py
module.
Like the API, the web page relies on a blueprint, which is initiated in the __init__.py
module.
The HTML and Static files for CSS required for rendering and styling web pages can be found under the templates
and static
folder. (Although there is nothing in the static folder at the moment)
Logging
Logging is handled through flask's logger. However, custom handlers for logging are created under the app/utils/logging.py
module, which are tied to application when initiated with the docker config. (Can be found under the config.py
module.)
The rotating handler creates rotating logs under the logs folder, while the stream handler logs to the terminal/client. Other logger handlers can be placed here such as an SMTP logger (for emailing errors).
Database Choice & Operations
Usually for smaller projects, databases such as SQLite is preferred for the ease of use. However, in most of the production environments, these databases are never used so learning how to set them up might be useless for larger commercial projects.
Keeping this in mind, even though the project is quite small, I went the extra mile to setup a proper PostgreSQL database. The configurations for this database is specified under the .env
file, and it is set as the default database.
Python uses psycopg2
driver to connect to postgres databases. It quite easy to install psycopg2 on Linux based OS, however you may need to get Homebrew on your Mac to make your installation easier for you.
Setting up a Postgres Database
Assuming that you have installed postgres database (if you haven't Homebrew is the way I prefer for installations on Mac, and with Ubuntu, its even easier), you can easily setup a database through your terminal.
After reaching the postgres terminal through a PSQL
command such as
sudo -u postgres psql
You can create a new user and make the user a superuser for your project by
create user tester with password 'password';
alter user tester superuser;
(Making the user a superuser makes things easier when creating tables or databases)
And then create a database and grant privileges locally by
create database stories;
grant all privileges on database stories to tester;
Granting privileges allows your user to make changes to your database.
Make sure you save these information, and add them to your .env
file so your code can make changes to the database
On your .env
file, you will want to set your database_host
variable to localhost
, and probably your database will be operating on port (database_port
) 5432
unless specified otherwise.
For this case, your database_name
will be stories
, database_user
will be tester
and database_password
will be password
.
This should do it with the database setup!
Migrations
Database migrations are handled through Flask's Migrate Package, which provides a wrapper around Alembic. Migrations are done for updating and creating necessary tables/entries in your database. Flask provides a neat way of handling these.
After exporting your flask CLI to point towards your application (for example in this case it can be done with):
export FLASK_APP=stories.py
You can find the necessary database commands with:
flask db
Initially, if you were to create an app from scratch, you would need to initiate your migrations with:
flask db init
In this case migrations folder is already there. So, you won't have to initiate it. Once you start altering your models, you will need to create a new migrations scripts. For example, if you add or remove fields from the existing models or create new models you would need to generate new migrations and update your database.
For generating new migrations, you can use:
flask db migrate
And for applying your new migrations to your database, you can use:
flask db upgrade
The project also creates a shortcut for upgrading, which is added to Flask's CLI:
flask deploy
Running the Application
Once you have setup your database, you are ready to run the application. Assuming that you have exported your app's path by:
export FLASK_APP=stories.py
You can go ahead and run the application with a simple command:
flask run
You can also run your app using Gunicorn, which a separate WSGI Server that plays very well with Flask:
gunicorn --reload stories:app
Docker Setup
The project also has docker functionality, which means if you have docker installed on your computer, you can run it using Docker as well!
Docker creates containers for you, and basically serves your application using these containers. The necessary setting files for the docker setup can be found under docker-compose.yaml
and Dockerfile
it self.
In this case, docker uses a prebuilt Python3.6 image that runs on Ubuntu, and creates Nginx reverse proxy and Postgres database containers to serve the application.
To build the docker image, fist, set your ENV
variable within your .env
file to docker
.
And then, run:
sudo docker-compose up --build
Once its built, it will do the necessary migrations for your application, and your app will be running straight away. You do not need to specify the --build
command a second time to run the docker compose instance:
sudo docker-compose up
Docker becomes especially useful while deploying your applications on servers, and makes the DevOps easier. You can read more about docker.
Finally
Hope this guide/template comes useful to you! If you have any feedback good or bad, please do let me know or feel free to fork and raise a PR. Would be happy to discuss possible improvements. Also, I have tried to leave useful comments within the code it self, so further explanation to what each module does can be found within the comments and docstrings.
Acknowledgements
Many thanks to Jose Rivera-Rubio for his help with the docker setup!
Todo and Improvements
- Add tests