This code base serves as starting point for writing your next Flask application.
This package is designed to allow developers to start working on their specific features immediately while also making it simple to deploy the project into production. It contains a number of configured extensions and libraries as well as unique features specifically built for this package. It also is completely dockerized, with both a docker-compose testenv and the ability to easily make images off of the application for pushing into production.
If you like this project you may also like my latest template, Rob's Awesome Python Template. It is updated with modern best practices and a variety of optional services.
- Tested on Python 3.3, 3.4, 3.5, 3.6, and 3.7
- Complete docker environment.
- Images for both the web application and the celery worker.
- Full user management system.
- Server side session storage.
- An API system with API tokens and route decorators.
- Well organized directories with lots of comments.
- Includes test framework (
py.test
andtox
) - Includes database migration framework (
alembic
, usingFlask-Migrate
) - Sends error emails to admins for unhandled exceptions
With thanks to the following Flask extensions and libraries:
- Beaker for caching and session management.
- Celery for running asynchronous tasks on worker nodes.
- Click for the creation of command line tools.
- Flask the microframework framework which holds this all together.
- Flask-Login allows users to login and signout.
- Flask-Migrate integrates Alembic into Flask to handle database versioning.
- Flask-SQLAlchemy integrates SQLAlchemy into Flask for database modeling and access.
- Flask-User adds user management and authorization features.
- Flask-WTF integrates WTForms into Flask to handle form creation and validation.
In addition the front end uses the open source versions of:
-
Database or LDAP Authentication - Applications built with this project can use the standard database backed users or can switch to LDAP authentication with a few configuration settings.
-
API Authentication and Authorization - this project can allow people with the appropriate role to generate API Keys, which in turn can be used with the
roles_accepted_api
decorator to grant API access to specific routes. -
Versatile Configuration System - this project can be configured with a combination of configuration files, AWS Secrets Manager configuration, and environmental variables. This allows base settings to be built into the deployment, secrets to be managed securely, and any configuration value to be overridden by environmental variables.
-
A
makefile
with a variety of options to make common tasks easier to accomplish. -
A Celery based asynchronous task management system. This is extremely useful for long running tasks- they can be triggered in the web interface and then run on a worker node and take as long as they need to complete.
First we recommend either cloning this repository with the "Use this template" button on Github.
We assume that you have make
and docker
.
# Clone the code repository into ~/dev/my_app
mkdir -p ~/dev
cd ~/dev
git clone https://github.com/tedivm/tedivms-flask my_app
cd my_app
# For the first run, and only the first run, we need to create the first round of SQLAlchemy models.
make init_db
# Create the 'my_app' virtual environment and start docker containers
make testenv
# Restart docker app container
docker-compose restart app
# Start a shell in the container running the application
docker-compose exec app /bin/bash
To set default configuration values on the application level- such as the application name and author- edit ./app/settings.py
. This should be done as a first step whenever using this application template.
A configuration file can be set with the environmental variable APPLICATION_SETTINGS
.
Configuration can be loaded from the AWS Secrets Manager by setting the environmental variables AWS_SECRETS_MANAGER_CONFIG
and AWS_SECRETS_REGION
.
Any environmental variables that have the same name as a configuration value in this application will automatically get loaded into the app's configuration.
Any installation can run with LDAP as its backend with these settings.
USER_LDAP=true
LDAP_HOST=ldap://ldap
LDAP_BIND_DN=cn=admin,dc=example,dc=org
LDAP_BIND_PASSWORD=admin
LDAP_USERNAME_ATTRIBUTE=cn
LDAP_USER_BASE=ou=users,dc=example,dc=org
LDAP_GROUP_OBJECT_CLASS=posixGroup
LDAP_GROUP_ATTRIBUTE=cn
LDAP_GROUP_BASE=ou=groups,dc=example,dc=org
LDAP_GROUP_TO_ROLE_ADMIN=admin
LDAP_GROUP_TO_ROLE_DEV=dev
LDAP_GROUP_TO_ROLE_USER=user
LDAP_EMAIL_ATTRIBUTE=mail
# Initialize the database. This will create the `migrations` folder and is only needed once per project.
make init_db
# This creates a new migration. It should be run whenever you change your database models.
make upgrade_models
# Start the Flask development web server
make testenv
Point your web browser to http://localhost/
You can make use of the following users:
- email
user@example.com
with passwordPassword1
. - email
dev@example.com
with passwordPassword1
. - email
admin@example.com
with passwordPassword1
.
# To run the test suite.
make run_tests
Flask-Dash was used as a starting point for this code repository. That project was based off of the Flask-User-starter-app.
- Robert Hafner (tedivms-flask) -- tedivm@tedivm.com
- Matt Hogan (flaskdash) -- matt AT twintechlabs DOT io
- Ling Thio (flask-user) -- ling.thio AT gmail DOT com