Flask Skeleton provides a base structure for a medium-sized Flask app. This incorporates several Flask best practices and is my default setup for whenever I create a new Flask project. This was built and tested with Python 2.
Here's the stuff you get right off the bat when using Flask-Skeleton:
- Bootstrap starter template
- Asset concatenation and minification (Alembic and Flask-Assets)
- Custom error (401, 403, 404, 500) templates
- Database migrations support (Flask-Migrate)
- Functional and unit testing boilerplate with examples (pytest and webtest)
- Heroku and Postgres configuration for fast deployment
- Modular Flask application architecture using Application Factories and Blueprints
- ORM integration (SQLAlchemy)
- Python static analysis tools (pylint and pep8)
- REPL connected to your database
- Secure user authentication with password hashing (Flask-Login and Flask-Bcrypt)
- User email activation (Flask-Mail) and password recovery
- Quickstart
- Installing
- Preparing a database
- Environment variables
- Running
- Tests
- Migrations
- Thanks
- Changelog
Because sometimes you just want to see it work
git clone [email protected]:nezaj/flask-skeleton.git
cd flask-skeleton
sudo pip install virtualenv
make virtualenv
source ~/.virtualenvs/flask-skeleton/bin/activate
./manage.py db upgrade
python -c 'import os; print "APP_KEY={}".format(os.urandom(24))' > .env # Generates random secret key for the app
./manage.py runserver
Now go to http://localhost:5000/ in your favorite browser. Huzzah!
You should build a virtualenv to contain this project's Python dependencies. The Makefile will create one for you and put it in ~/.virtualenvs/flask-skeleton.
sudo pip install virtualenv
make virtualenv
Then activate it:
source ~/.virtualenvs/flask-skeleton/bin/activate
Instead of activating it manually like that, you might find it convenient to use virtualenvwrapper for working with virtualenvs:
sudo pip install virtualenvwrapper
source /usr/local/bin/virtualenvwrapper.sh
workon flask-skeleton
If you ever need to upgrade it or install packages which appeared since your last run, just run make virtualenv again.
You need to pick a database to run the app against. By default, the development configuration points to a local SQLlite database dev.db located at the top level directory. Run the following to create the database
./manage.py db upgrade
You can also launch a repl connected to your database. By default this will connect to the database defined by SQLALCHEMY_DATABASE_URI in DevelopmentConfig from the settings module
./manage.py db repl
APP_ENV=prod ./manage.py db repl # Connect to prod database
Most of the app configuration is defined in the settings module. However, some necessary but sensitive configuration settings like secret keys, emails, and production database URIs are not (and should not) be part of source control. Instead, we import these settings from another file and create environment variables at runtime. Flask Skeleton will look for key-value pairs (in the form of KEY=VALUE) defined in the .env file at the top level directory. The .env file should not be part of source control and included in our .gitignore.
At a minimum, we must define an APP_KEY variable which will be used as the secret key for signing cookies in our application. We can create the .env file and a random value for APP_KEY in one go
python -c 'import os; print "APP_KEY={}".format(os.urandom(24))' > .env
To specify additional key-value pairs, add them on separate lines in your newly generated .env file. These will be imported whenever you run a ./manage command.
Once you've installed all the dependencies, prepared a database, and configured your environment variables you're ready to run the app.
./manage.py runserver
You may also specify the port and host like so:
./manage.py runserver --port=8080 --host=0.0.0.0 # listening on port 8080 to requests coming from any source
By default, the app runs using the DevelopmentConfig configuration defined in the settings module. To point to a different configuration module, you can set the APP_ENV variable:
APP_ENV=test ./manage.py runserver
This will also run against the database specified in that configuration rather than the one you just set up above.
The environment is preconfigured to contain pep8 and pylint, popular Python static analysis tools. pytest and webtest are also used for automated testing. You can run all the tests via make check
Alembic and flask-migrate are used for keeping a revision history of database schemas. You can see the history at any time:
./manage.py db history
Common operations available are:
# ensures that the current database is up-to-date
./manage.py db upgrade
# rolls back the database to the previous revision
./manage.py db downgrade
These are thin wrappers around the underlying alembic commands. For a full list of commands
./manage.py db --help
If you make changes to the schema, you'll want to generate a new Alembic revision.
./manage.py db migrate -m "Short description of your change"
This will create a new revision file in the migrations directory with upgrade and downgrade scripts. You should inspect it for accuracy. Type ./manage.py db upgrade to test it out. If all seems good, then commit the alembic revision to git with your schema changes. To run the upgrade on your production database
APP_ENV=prod ./manage.py db upgrade`
User activation and password recovery involves sending emails from the application. The default configured mail server is smtp.googlemail.com. You can edit the settings module if you wish to use a different server. In order to send emails you will need to export authentication credentials to your environment. You can append these to your .env file
echo "[email protected]" >> .env
echo "APP_MAIL_PASSWORD=my-mail-password" >> .env
- @mquander for your patience and mentoring
- @miguelgrinberg for your excellent flask tutorial
- @sloria for your great starter template
- First release
- Application factories and Blueprints
- Bootstrap starter template
- Asset concatenation and minification
- Custom error (401, 403, 404, 500) templates
- Database migrations support
- Database REPL
- Flask-Login for user authentication
- Flask-Bcrypt for password hashing
- Flask-Mail for sending emails
- Functional and unit testing boilerplate with examples
- Heroku and Postgres configuration for fast deployment
- pep8 and pylint for static analysis
- SQLAlchemy integration
- Token based account activation and password recovery
- User and UserPasswordToken models