Skip to content

Latest commit

 

History

History
254 lines (188 loc) · 14.3 KB

README.md

File metadata and controls

254 lines (188 loc) · 14.3 KB
Raw

Google App Engine Boilerplate Legacy

This Project was Sponsored by PyCharm

NOTE: This Project is Legacy and uses the first technology used by Google App Engine, like webapp2 as Python Framework and DataStore as Data Base. On 2016 this project was legacy and it is recommedable to use moderm technologies like Flask or Django as Framework, MySQL as database. Thanks everybody for their contributions, The creator of this project is honored that it helps to bring web technology to the world.

Intro

Google App Engine Boilerplate gets your project off the ground quickly using the Google App Engine platform. Create powerful applications by using the latest technology supported on Google App Engine. It will introduces new developers to App Engine and advanced developers to follow best practices.

What's a Boilerplate?

A Boilerplate is used to describe sections of code that can be reused over and over in new contexts or applications which provides good default values, reducing the need to specify program details in every project. (wikipedia)

What makes this Boilerplate Amazing?

It is fully featured, actively maintained, and uses the latest and most supported technologies of Google App Engine.

New to Google App Engine? Learn about it by watching this video of @bslatkin or reading the official documentation.

Get started in just a few easy steps

  1. Download the last version of the App Engine SDK for Linux, Mac OS or Windows.
  2. Download or clone the code of this Boilerplate (here)
  3. Run locally (instructions).
  4. Set your 'application' name in app.yaml
  5. Set custom config parameters in bp_content/themes config/localhost.py, config/testing.py and config/production.py like secret key, recaptcha code, salt and other.
  • Boilerplate will identify which config file to use in local, unit testing and production.
  • To get started, look the default settings in bp_includes/config.py. Those settings will be overwrite for your config files.
  • Most of the default settings will need to be changed to yield a secure and working application.

  1. Set Authentication Options dropdown to Federated Login in the Google App Engine control panel (or if you do not want federated login, set enable_federated_login to false in config.py)

  2. Deploy it online (instructions - recommended setup: python 2.7, high replication datastore)

    • gcloud config set project sandengine; gcloud app deploy -q app.yaml cron.yaml

Please note that your custom application code should be located in the bp_content folder within your own theme. The intention is that separating the boilerplate code from your application code will avoid merge conflicts as you keep up with future boilerplate changes.

Functions and features

  • Authentication (Sign In, Sign Out, Sign Up)
  • Federated Login - login via your favorite social network (Google, Twitter, etc...) powered by OpenID and OAuth
  • Reset Password
  • Update User Profile
  • Contact Form
  • Client side and server side form validation
  • Automatic detection of user language
  • Support for many Languages (English, Spanish, Italian, French, Chinese, Indonesian, German, Russian, etc)
  • Visitors Log
  • Notifications and Confirmation for users when they change their email or password
  • Responsive Design for viewing on PCs, tablets, and mobile phones (synchronized with Twitter-Bootstrap project)
  • Mobile identification
  • Unit Testing
  • Error handling
  • Basic user management features available under /admin/users/ for Google Application Administrators

Resources

Boilerplate has a Google group (gae-boilerplate) for discussions and a Twitter account (@gaeboilerplate) for sharing related resources.

Open Source

If you want to add, fix or improve something, create an issue or send a Pull Request.

Before committing fixes we recommend running the unitests (in the boilerplate package). This will help guard against changes that accidently break other code. See the testing section below for instructions.

Feel free to commit improvements or new features. Feedback, comments and ideas are welcome.

Run

  • You can run this project directly from terminal with Fabric.

    fab start

  • Also you can run it clearing datastore.

    fab start:clear

Unit Testing

Requirements

  • Install pip with distribute in order to install next packages.

  • Before running unittests it is necessary to install webtest, mock, and pyquery in your local python installation.

      sudo pip install webtest
  sudo pip install mock
  sudo pip install pyquery

  • The best way to run unittests is though Fabric.

      sudo pip install Fabric

Running Unit Tests

  • To run unittests with Fabric run fab test command in terminal.
  • Also Unit tests can be run via testrunner or in Eclipse by right clicking on the web folder and selecting "run as..." -> "Python unit-test".
  • You may need to add /boilerplate/external to your python path.

Adding yours Unit Test

  • Please add unittests for your application to your handler folder in a test.py file.
  • Your own unittests can be created similarly to those in the boilerplate. Inheriting from boilerplate.lib.test_helpers.HandlerHelpers will provide access to convenient handler testing methods used by the boilerplate.

Deploy

  • To deploy your project with Fabric, just run this command in Terminal.

    fab deploy

  • Remember to change application, version, theme in app.yaml according to your project.

Technologies used

  • Python 2.7.5
  • NDB 1.0.10 (The best datastore API for the Google App Engine Python runtime).
  • Jinja2 2.6 (A fully featured template engine for Python).
  • WTForms-1.0.2 (Forms validation framework keeping user interaction secure and flexible with or without javascript).
  • Babel-0.9.6 and gaepytz-2011h (Industy standard internationalization renders the site in multiple languages).
  • webapp2 2.5.2 (A lightweight Python web framework, the most compatible with Google App Engine).
    • webapp2_extras.sessions
    • webapp2_extras.routes
    • webapp2_extras.auth
    • webapp2_extras.i18n
  • Code written following the Google Python Style Guide
  • Unit testing with unittest, webtest, pyquery
  • OpenID library provided by Google App Engine
  • OAuth2 for federated login providers that do not support OpenID

Front-end Technologies

Help to translate to new languages or improve old translations

In each locale//LC_MESSAGES directory there is a file messages.po. Please help us translate the text in these files. msgid is the text in English. msgstr is the translation to the language indicated by the locale code. For example:

msgid "Change your password"

msgstr "Cambiar tu contraseña"

Requirements

  • Install before pip with distribute_setup.py (Read the environment setup document)

    sudo pip install babel
sudo pip install jinja2

Translating

  • To execute the translation, run these two commands. (before the second one, go to locale folder to include your translation)

    fab lang
fab lang:compile

Working with Internationalization (i18n)

This boilerplate comes bundled with babel, pytz, and automatic language detection which together provide powerful internationalization capability. Text to be translated needs to be indicated in code and then translated by users like you after which it is compiled for speed.

Adding or updating text to be translated or adding new languages requires more work as indicated in the steps below:

  1. Text to be translated should be enclosed in _("text to translate") in *.py files.

    • {{..._("text to translate")...}}
    • {%..._("text to translate")...%}

  2. In html templates translated text is indicated by:

    • {% trans %}text to translate{% endtrans %}

    NOTE: Translations can be added to other types of files too. See babel.cfg and babel.cfg documentation

  3. Obtain pybabel to perform the steps below. You will need to install and compile jinja2 and babel. Note that you may need to first install setuptools and easy_install. pybabel.exe can be run from the Scripts directory in your python installation.

    • easy_install jinja2 babel

  4. Babel then needs to find all translationed text blocks throughout code and templates. After installing pybabl run this command to extract messages (assuming ./ is the location of this boilerplate): pybabel extract -F ./locale/babel.cfg -o ./locale/messages.pot ./ --sort-output --no-location --omit-header

  5. Update translations of existing languages or add new languages

    1. Update translations of existing languages by running this command for each locale: pybabel update -l es_ES -d ./locale -i ./locale/messages.pot --previous --ignore-obsolete Run this command for each locale by replacing es_ES in the command. Locale names are the directory names in ./locale.
    2. Add new languages: Run this command for each new language to add. You will need to replace es_ES in the command with the locale code to add: pybabel init -l es_ES -d ./locale -i ./locale/messages.pot Add the locale to the locales array in your themes/<your_theme>/config/. Instructions on how to pick a locale code are provided in the comments above the array.

  6. Provide translations for each language In each locale//LC_MESSAGES directory there is a file messages.po. Users translate the strings in these files. msgid is the text in English. msgstr is the translation to the language indicated by the locale code. For example:

    • msgid "Change your password"
    • msgstr "Cambiar tu contraseña"

  7. Compile translations Run: pybabel compile -f -d ./locale

See webapp2's tutorial and pybabel's docs for more details.

Disabling i18n

i18n can be disabled and language options hidden. Set locales in config.py to None or empty array [] to do this. This may be useful to provide a performance boost or simplify sites that serve a market with only one language. The locale directory can be safely removed to save space if not needed but the babel and pytz directories cannot be removed without breaking code (imports and trans statements) at this time.

Security

SSL

  • SSL is enabled site wide by adding secure: always to the section: - url: /.* in app.yaml (remove this line to disable)
  • SSL either requires a free google app engine *.appspot.com domain or a custom domain and certificate
  • Alternatively SSL can be enabled at a controller level via webapp2 schemes. Use the secure_scheme provided in routes.py
  • It is recommended to enable ssl site wide to help prevent session hijacking

Passwords

  • Passwords are hashed and encrypted with SHA512 and PyCrypto.

CSRF

Acknowledgements

Google App Engine Boilerplate is a collaborative project created by coto which is bringing to you thanks to the help of these amazing people

Top 10: Primary contributors:

Flask Boilerplates