Flask on App Engine Project Template

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

About Flask

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

See http://flask.pocoo.org for more info.

Setup/Configuration

1. Download this repository via git clone git@github.com:kamalgill/flask-appengine-template.git or download the tarball at http://github.com/kamalgill/flask-appengine-template/tarball/master
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/models.py
5. Configure application views at src/application/views.py
6. Configure URL routes at src/application/urls.py
7. Configure forms at src/application/forms.py
8. Add a secret_keys.py file at src/application/secret_keys.py, with the following contents:

	CSRF_SECRET_KEY = '{MY_SECRET_CSRF_KEY}'
	SESSION_KEY = '{MY_SECRET_SESSION_KEY}'

where the keys are a randomized string of characters.

Or, run the generate_keys.py script at src/application/generate_keys.py to generate the keys file.

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
	secret_keys.py

Front-end Customization

1. Customize the main HTML template at src/application/static/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/aplication/templates/404.html

Testing the Application

To test the application using App Engine's development server, use dev_appserver.py

	dev_appserver.py src/

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

Deploying the Application

To deploy the application to App Engine, use appcfg.py update

	appcfg.py update src/

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

Folder structure

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

	src/
	|-- application (application code)
	|-- flask (Flask core)
	|-- flaskext (Flask extensions, inc. Flask-WTF)
	|-- jinja2 (template engine)
	|-- simplejson (required by Jinja2)
	|-- werkzeug (WSGI utilities for Python-based web development)
	`-- wtforms (Jinja2-compatible web form utility)

The application code is located at src/application.

	application/
	|-- __init__.py (initializes Flask app)
	|-- decorators.py (decorators for URL handlers)
	|-- forms.py (web form models and validators)
	|-- models.py (App Engine datastore models)
	|-- settings.py (settings for Flask app)
	|-- static
	|	|-- css
	|	|	`-- main.css (custom styles)
	|	|-- img
	|	|	|-- favicon.ico (replace with custom favicon)
	|	|	`-- favicon.png
	|	`-- js
	|		|-- main.js (custom javascript)
	|		`-- modernizr-1.6.min.js (HTML5 enabling and detection)
	|-- templates
	|	|-- 404.html (not found page)
	|	|-- base.html (master template)
	|	|-- list_examples.html (example list-based template)
	|	`-- new_example.html (example form-based template)
	|-- tests.py (unit tests)
	|-- urls.py (URL dispatch routes)
	`-- views.py (Handlers for URL routes defined at urls.py)

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 com.apple.quarantine .
	xattr -rd com.macromates.caret .

Note: Windows users may safely ignore the xattr fix

Licenses

See licenses/ folder

Package Versions

• Flask: 0.6
• Flask-WTF: 0.3.3
• Jinja2: 2.5.5
• simplejson: 2.1.1
• Werkzeug: 0.6.2
• WTForms: 0.6.1

Credits

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

HTML5-based main template (templates/base.html) extracted from HTML5 Boilerplate

CSS reset, fonts, grids, and base styles provided by YUI 3