Thursday, April 8, 2010

Setting up web2py for use with Google App Engine

This tutorial assumes you are using a linux based operating system (or perhaps osx). If you are using Windows the issue of creating symbolic links won't apply, but the level of nesting should apply and may work for you if you nest the folders in this manner:
    google_app_engine/web2py/applications/myappname
The whole issue of creating symbolic links isn't central to this process, but it will save you a ton of headaches when it comes to upgrading to different versions of web2py or google app engine (or if you are tracking changes to your application in a versioning system).
First, sign up for an account with Google App Engine (GAE) here:
https://appengine.google.com/
Then, click on the button to "Create an Application"
Note: web2py allows you to serve multiple applications within one instance of web2py, so you may want to name your google app engine application with a more encompassing name, like "mywebapps"
Once we're done, your web application will live at a url like:
http://mywebapps.appspot.com/mywebapp/
Note: remember what you've named your google app engine application (whatever you chose in place of "mywebapps") we'll be using this name later on in the tutorial.
1) Download the latest Google Application Engine development environment here: http://code.google.com/appengine/downloads.html#Google_App_Engine_SDK_for_Python
Save the archived file to the root of your web development directory, such as:
    /home/joesmith/webdev/google_app_engine/
2) Download the latest web2py source files. Save this to the root of your web development directory as well. Then unzip the archive to a folder, like:
    /home/joesmith/webdev/web2py/
3) cd into the web2py directory, and start the web2py development server by typing in the terminal shell:
    python web2py.py
4a) Create your app via web2py's browser based interface at:
http://localhost:8000/admin/default/site
In the box labeled "Create New Application", write your application name into the textbox, then click on the button labeled "Create"
4b) untested: you may be able to test this with one of the sample apps that ships with web2py at
http://localhost:8000/examples/default/examples
4c) untested: you may also be able to test this with one of the user contributed apps here:
http://web2py.com/appliances
5) stop web2py (via the gui) or by closing the terminal window.
6) cd into the web2py applications directory like this:
    cd webdev/web2py/applications/
7) move your newly created application up to the level of your web development directory, like this:
    mv myappname ../../
8) Create a symbolic link within your web2py applications directory to your newly created application (now living at the root of the web development directory):
    ln -sf /home/joesmith/webdev/myappname .
9) cd into the google app engine directory you created earlier like this:
    cd ~/webdev/google_app_engine
create a symbolic link to the web2py directory from within the root of the google app engine directory, like this:
    ln -sf /home/joesmith/web2py .
10) cd into the web2py directory and edit the app.yaml file.
change the first line which reads:
application: web2py
version: 1
api_version: 1
runtime: python

So that it contains the name of your application instead (the name you used to name your google app engine application... whatever you chose in place of "mywebapps" in the first part of the tutorial):
application: mywebapps
version: 1
api_version: 1
runtime: python

You may also want to change the version of the of your app.  I recently discovered in this blog post that:

App Versions are strings, not numbers

Although most of the examples show the 'version' field in app.yaml and appengine-web.xml as a number, that's just a matter of convention. App versions can be any string that's allowed in a URL. For example, you could call your versions "live" and "dev", and they would be accessible at "live.latest.yourapp.appspot.com" and "dev.latest.yourapp.appspot.com".


Lastly, you will likely want to change references to the welcome app for the favicon.ico and the robots.txt file to reference the static folder for your app.  A simple search and replace will turn this:

applications/welcome/static/favicon.ico

into this:

applications/mywebapps/static/favicon.ico

You can now save your your app.yaml file.

11) cd up to the google app engine directory. In the terminal shell, tart the google app engine developement server:
    python dev_appserver.py web2py
12) test your application at http://localhost:8080
Note: gae uses two .yaml configuration files:
app.yaml (already covered) and
index.yaml
The index.yaml file gets created the first time you run web2py under the gae dev server. Afterward, you will find the file here, for example:
/home/joesmith/webdev/google_appengine/web2py/index.yaml
before updating your app to Google App Engine, be sure to run the app locally under the GAE dev server and then run through every feature(??) so that GAE builds the index completely. There may be a more elegant way to do this, however, I ran through my app using Selenium IDE and then replayed the app each time I need to test / rebuild the index. You can see an example of the file that it creates here: http://code.google.com/p/pledgedrivetracker/source/browse/pledgedrives/static/selenium_tests
13) updating your new web2py app on gae
    python appcfg.py update web2py
14) Test your app on the live, Google App Engine production server:
Your web application will live at a url like:
http://mywebapps.appspot.com/mywebapp/
15) This might be a good time to use that same Selenium IDE script that you used earlier to run through your app to test it in production.
16) Notes and caveats:
If, at a later date, you change the indexes you need to run:

python appcfg.py update_indexes web2py

Because we are using the Web2py framework (and the DAL) you do not have to use the GAE API to talk to the Google's Big Table database.
Google App Engine replaces web2py's error ticketing system with their own tool to display log messages for staying informed about errors or for keeping informed about the performance of your app.

4 comments:

John Tynan said...

I just received a nice note from Massimo Di Pierro clarifying one point: "you can use OR for GAE queries as long all the OR subqueries refer to the same field. BELONGS also works on GAE."

Alexei Vinidiktov said...

Here is information about "OR, LIKE, BELONGS, and more on Google App Engine". (supported since 1.69.1)

http://web2pyslices.com/main/slices/take_slice/16

Jiten said...

thanks for such a great and non confusing tutorial ..

now i will do something useful..

magrelo said...

Yees, now my app is running on Google App Engine ! Thank you man !!!!!!!!!