ghandylan / flask-template

My starter template for Flask projects

Flask Starter Template

Rationale

Flask is a "micro-framework" based on Python used to build web applications. It contains only the barebones when creating projects. As a result, when I create new projects, I always find myself installing the dependencies I need based on the projects. This takes too much effort and becomes repetitive. Since Flask is pretty much unopinionated, I built this repository so that everyone can use it as a template and save time when setting up projects for web development. It includes basic plugins that I use such as database interaction, user management, security, and db migrations.

This is a starter template for Flask projects.

It includes the following features:

• Role based authentication with Flask-Login which can be edited on rbac.py
• MySQL database connection with mysqlclient
• ORM support with Flask-SQLAlchemy
• .env file support with python-dotenv
• Powerful template engine Jinja2
• Database migration support with Flask-Migrate
• Password hashing with bcrypt
• Flask-WTF forms with CSRF protection

Pre-requisites:

• Python 3.6 or above
• MySQL 5.7 or above
• IDE of your choice

To use this template:

1. Clone this repository using git clone git clone https://github.com/ghandylan/flask-template

2. Unzip the folder and open it in your favorite IDE like PyCharm, VSCode, etc.

3. Open the terminal and create a virtual environment using python -m venv <env_name>

4. Activate the virtual environment using <env_name>\Scripts\activate on Windows or source <env_name>/bin/activate on Linux/MacOS.

5. Run pip install -r requirements.txt to install all the dependencies.

6. Create a .env file and add the following variables:

   • SECRET_KEY - A secret key for your application.
   • SQLALCHEMY_DATABASE_URI - The URI for your MySQL database.
     • Example: mysql://<username>:<password>@localhost:3306/<db_name>
   • SQLALCHEMY_TRACK_MODIFICATIONS - Set it to False.

7. Make sure your MySQL server is running and create a database with the name you specified in the .env file.

8. Run the following commands to perform database migrations with Flask-Migrate:

   • flask db init
   • flask db migrate
   • flask db upgrade

   Should you encounter any errors with database migrations, run flask db stamp head and then run the above excluding the flask db init command.

9. Run python app.py to start the server.

Files in the project:

1. app.py - The main file which contains the Flask application.
2. config.py - Contains the configuration for the Flask application. Make sure to use environment variables for sensitive information.
3. models.py - Contains the database models. Feel free to edit it as per your requirements.
   • By default, it contains a User model which can be used for authentication.
   • User's primary key is a UUIDv4 string to enforce data integrity.
4. rbac.py - Contains the role based access control logic.
5. forms.py - Contains the forms for the application. Feel free to edit it as per your requirements.

Folders in the project:

1. templates contains the HTML templates for the application. Inside that folder, the base.html file contains the base template which is extended by all other templates. Bootstrap 4 is used for styling the templates.
2. static contains the static files like CSS, JS, images, etc.
3. migrations contains the database migration files generated by Flask-Migrate.
4. venv contains the virtual environment for the project.
5. blueprints contains the blueprints for the application. Use it to organize your application to user/admin views.