Boilerplate project template for running Flask on Google App Engine
Python JavaScript HTML CSS

Flask on App Engine Project Template

Boilerplate project template for running a Flask-based application on Google App Engine (Python)

Note: This project isn't as actively maintained as I would like (although pull requests are still welcome). You may want to investigate similar projects listed below:

About Flask

Flask is a BSD-licensed microframework for Python based on Werkzeug, Jinja2 and good intentions.

See for more info.


  1. Download this repository via git clone or download the tarball at
  2. Copy the src/ folder to your application's root folder
  3. Set the application id in src/app.yaml
  4. Configure datastore models at src/application/
  5. Configure application views at src/application/views/
  6. Configure URL routes at src/application/
  7. Configure forms at src/application/
  8. Add the secret keys for CSRF protection by running the script at src/application/, which will generate the secret keys module at src/application/

Note: Copy the .gitignore file from the tarball folder's root to your git repository root to keep the secret_keys module out of version control.

Or, add the following to your .(git|hg|bzr)ignore file

  # Keep secret keys out of version control

Install python dependencies

The local dev environment requires installation of Jinja2, PIL, and simplejson, which can be installed via:

  pip install -r requirements_dev.txt

Front-end Customization

  1. Customize the main HTML template at src/application/templates/base.html
  2. Customize CSS styles at src/application/static/css/main.css
  3. Add custom JavaScript code at src/application/static/js/main.js
  4. Customize favicon at src/application/static/img/favicon.ico
  5. Customize 404 page at src/application/templates/404.html

Previewing the Application

To preview the application using App Engine's development server, use src/

Assuming the latest App Engine SDK is installed, the test environment is available at http://localhost:8080

Admin Console

The admin console is viewable at http://localhost:8000 (note distinct port from dev app server)


The handy Flask-Cache extension is included, pre-configured for App Engine's Memcache API. Use the "Flush Cache" button at http://localhost:8000/memcache to clear the cache.


Place all your tests in src/tests directory. Test runner is placed in src directory. To run your tests simply go to src directory and do:

  python path/to/your/googleappengine/installation

Path to your local google app engine installation must be provided as first argument to the script. If the path is long and you don't like to type it each time you run the tests you can also hardcode it in, just edit the variable SDK_PATH and set it to your google app engine folder.

Before running tests set evironment variable FLASK_CONF to the value TEST.

In Linux this is done by:


In Powershell:

  [Environment]::SetEnvironmentVariable("FLASK_CONF", "TEST", "User");

Remember to restart Powershell. Change of environment variable will take place after restarting Powershell.

You can specify your testing configuration (e.g. separate database for tests results) in src/application/

To switch back to development configuration just set FLASK_CONF to DEV.

Deploying the Application

To deploy the application to App Engine, use update update src/

The application should be visible at http://{YOURAPPID}

Folder structure

The App Engine app's root folder is located at src/.

  |-- app.yaml (App Engine config file)
  |-- application (application code)
  |-- index.yaml (App Engine query index definitions)
  |-- lib/
  |   |-- blinker/ (library for event/signal support)
  |   |-- flask/ (Flask core)
  |   |-- flask_cache/  (Flask-Cache extension)
  |   |-- flask_debugtoolbar/  (Port of Django Debug Toolbar to Flask)
  |   |-- flaskext/ (Flask extensions go here)
  |   |-- gae_mini_profiler/ (Appstats-based profiler)
  |   |-- (required by Flask >= 0.10
  |   |-- werkzeug/ (WSGI utilities for Python-based web development)
  |   `-- wtforms/ (Jinja2-compatible web form utility)
  |-- tests/ (unit tests)

The application code is located at src/application.

  |-- (initializes Flask app)
  |-- (decorators for URL handlers)
  |-- (web form models and validators)
  |-- (App Engine datastore models)
  |-- (settings for Flask app)
  |-- static
  | |-- css
  | | |-- bootstrap-*.css (Twitter Bootstrap styles)
  | | |-- fontawesome-*.css (Fontawesome styles)
  | | `-- main.css (custom styles)
  | |-- font
  | | `various fontawesome font files
  | |-- img
  | | |-- favicon.ico
  | | |-- favicon.png
  | | `-- glyphicons-*.png (Twitter bootstrap icons sprite)
  | `-- js
  |   |-- main.js (site-wide JS)
  |   `-- lib/ (third-party JS libraries)
  |     |--bootstrap-*.js (Bootstrap jQuery plugins
  |     `--modernizer-*.js (HTML5 detection library)
  |-- templates
  | |-- includes/ (common include files)
  | |-- 404.html (not found page)
  | |-- 500.html (server error page)
  | |-- base.html (master template)
  | |-- list_examples.html (example list-based template)
  | `-- new_example.html (example form-based template)
  |-- (URL dispatch routes)
  |-- views
  |   |-- admin
  |     `-- *.py (Views which require authentification)
  |   |-- public
  |     `-- *.py (Public views)

Removing Extended Attributes (@ flag)

A few of the files in the source tree were uploaded (with apologies) to GitHub with extended attributes (notice the '@' symbol when running ls -al).

To remove the extended attributes, use xattr -rd at the root of the src/ folder.

  xattr -rd .
  xattr -rd com.macromates.caret .

Note: Windows users may safely ignore the xattr fix


See licenses/ folder

Package Versions

  • Blinker: 1.1
  • Bootstrap: 2.3.1
  • Flask: 0.10
  • Flask-Cache 0.10.1
  • Flask-DebugToolbar: 0.7.1
  • Flask-WTF: 0.6
  • FontAwesome: 3.0
  • itsdangerous: 0.22
  • Jinja2: 2.6 (included in GAE)
  • jQuery: 1.9.1 (set in base.html)
  • Modernizr: 2.6.2
  • Werkzeug: 0.8.3
  • WTForms: 1.0.5


Project template layout was heavily inspired by Francisco Souza's gaeseries Flask project

Incorporates Flask-DebugToolbar by Matt Good et. al. and Flask-Cache by Thadeus Burgess

Layout, form, table, and button styles provided by Bootstrap

Font Awesome by Dave Gandy

HTML5 detection provided by Modernizr 2 (configured with all features)