From 5810ad115d731cbd195813395e4ef2b032924779 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 3 May 2009 23:47:27 +0000 Subject: Add GAE tutorial plus make CHANGES.txt renderings work. --- docs/tutorials/gae/index.rst | 201 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 201 insertions(+) create mode 100644 docs/tutorials/gae/index.rst (limited to 'docs/tutorials') diff --git a/docs/tutorials/gae/index.rst b/docs/tutorials/gae/index.rst new file mode 100644 index 000000000..07aa7ccf4 --- /dev/null +++ b/docs/tutorials/gae/index.rst @@ -0,0 +1,201 @@ +Running :mod:`repoze.bfg` on Google's App Engine +================================================ + +As of :mod:`repoze.bfg` version 0.8, it is possible to run a +:mod:`repoze.bfg` application on Google's `App Engine +`_. Content from this tutorial was +contributed by "YoungKing", based on the `"appengine-monkey" tutorial +for Pylons `_. +This tutorial is written in terms of using the command line on a UNIX +system; it should be possible to perform similar actions on a Windows +system. + +.. note:: :term:`chameleon.zpt` cannot be used on Google App Engine + due to GAE environment limitations, so the tutorial is presented in + terms of using :term:`Jinja2` as the templating language in the + generated BFG application. + +#. Download Google's `App Engine SDK + `_ and install it + on your system. + +#. Use Subversion to check out the source code for + ``appengine-monkey``. + + .. code-block:: bash + + $ svn co http://appengine-monkey.googlecode.com/svn/trunk/ appengine-monkey + +#. Use ``appengine_homedir`` to create a :term:`virtualenv` for your + application. + + .. code-block:: bash + + $ export GAE_PATH=/usr/local/google_appengine + $ python2.5 appengine-homedir.py --gae $GAE_PATH bfgapp + + Note that ``$GAE_PATH`` should be the path where you have unpacked + the App Engine SDK. (On Mac OS X at least, + ``/usr/local/google_appengine`` is indeed where the installer puts + it). + + This will set up an environment in ``bfgapp/``, with some tools + installed in ``bfgapp/bin``. There will also be a directory + ``bfgapp/app/`` which is the directory you will upload to + appengine. + +#. Install :mod:`repoze.bfg.jinja2` into the virtualenv + + .. code-block:: bash + + $ cd bfgapp/ + $ bin/easy_install -i http://dist.repoze.org/bfg/dev/simple/ repoze.bfg.jinja2 + + This will install :mod:`repoze.bfg` in the environment. + +#. Create your application + + We'll use the standard way to create a :mod:`repoze.bfg` + application, but we'll have to move some files around when we are + done: + + .. code-block:: bash + + $ rm -rf bfgapp + $ bin/paster create -t bfg_jinja2_starter bfgapp + $ mv bfgapp aside + $ mv aside/bfgapp . + $ rm -rf aside + +#. Edit ``config.py`` + + .. code-block:: python + + APP_NAME = 'bfgapp.run:app' + APP_ARGS = ({},) + +#. Edit ``runner.py`` + + To prevent errors for ``import site``, add this code stanza before + ``import site`` in app/runner.py: + + .. code-block:: python + + import sys + sys.path = [path for path in sys.path if "site-packages" not in path] + import site + + You will also need to comment the ``assert`` in the file. + +#. Run the application. ``dev_appserver.py`` is typically installed + by the SDK in the global path but you need to be sure to run it + with Python 2.5 (or whatever version of Python your GAE SDK + expects). + + .. code-block:: python + + $ cd ../.. + $ python2.5 /usr/local/bin/dev_appserver.py bfgapp/app/ + + Startup success looks something like this:: + + [chrism@vitaminf bfg_gae]$ python2.5 /usr/local/bin/dev_appserver.py bfgapp/app/INFO 2009-05-03 22:23:13,887 appengine_rpc.py:157] Server: appengine.google.com + INFO 2009-05-03 22:23:13,898 appcfg.py:320] Checking for updates to the SDK. + INFO 2009-05-03 22:23:14,034 appcfg.py:334] The SDK is up to date. + WARNING 2009-05-03 22:23:14,035 datastore_file_stub.py:368] Could not read datastore data from /var/folders/dB/dByJ-qkiE6igZD4Yrm+nMk+++TI/-Tmp-/dev_appserver.datastore + WARNING 2009-05-03 22:23:14,035 datastore_file_stub.py:368] Could not read datastore data from /var/folders/dB/dByJ-qkiE6igZD4Yrm+nMk+++TI/-Tmp-/dev_appserver.datastore.history + WARNING 2009-05-03 22:23:14,045 dev_appserver.py:3240] Could not initialize images API; you are likely missing the Python "PIL" module. ImportError: No module named _imaging + INFO 2009-05-03 22:23:14,050 dev_appserver_main.py:463] Running application bfgapp on port 8080: http://localhost:8080 + +#. Hack on your bfg application, using a normal run, debug, restart + process. + +#. `Sign up for a GAE account `_ + and create an application. You'll need a mobile phone to accept an + SMS in order to receive authorization. + +#. Edit the application's ID in ``app.yaml`` to match the application + name you created during GAE account setup. + + .. code-block:: python + + application: mycoolbfgapp + +#. Upload the application + + .. code-block:: python + + $ python2.5 /usr/local/bin/appcfg.py update bfgapp/app + + You will almost certainly find that you hit the 1000-file GAE file + limit. + + .. code-block:: python + + HTTPError: HTTP Error 400: Bad Request + Rolling back the update. + Error 400: --- begin server output --- + Max number of files and blobs is 1000. + --- end server output --- + + You will be able to get around this by zipping libraries. You can + use ``pip`` to create zipfiles from packages. For example: + + .. code-block:: python + + $ bin/pip zip -l + + This shows your zipped packages (by default, none) and your + unzipped packages. You can zip a package like so: + + .. code-block:: python + + $ bin/pip zip pytz-2009g-py2.5.egg + + Note that it requires the whole egg file name. A the time of this + tutorial's writing, the 1000 file limit can be subverted by causing + the following packages to be zipped: + + - pytz + - chameleon.core + - chameleon.zpt + - zope.i18n + - zope.testing + + After zipping, a successful upload looks like so:: + + [chrism@vitaminf bfgapp]$ python2.5 /usr/local/bin/appcfg.py update ../bfgapp/app/ + Scanning files on local disk. + Scanned 500 files. + Scanned 1000 files. + Initiating update. + Cloning 761 application files. + Cloned 100 files. + Cloned 200 files. + Cloned 300 files. + Cloned 400 files. + Cloned 500 files. + Cloned 600 files. + Cloned 700 files. + Uploading 12 files. + Deploying new version. + Checking if new version is ready to serve. + Will check again in 1 seconds. + Checking if new version is ready to serve. + Will check again in 2 seconds. + Checking if new version is ready to serve. + Will check again in 4 seconds. + Checking if new version is ready to serve. + Will check again in 8 seconds. + Checking if new version is ready to serve. + Will check again in 16 seconds. + Checking if new version is ready to serve. + Closing update: new version is ready to start serving. + Uploading index definitions. + +#. Visit ".appspot.com" in a browser. + + + + + -- cgit v1.2.3