Setting up App Engine Patch Locally on Ubuntu

Since the latest release of Google App Engine SDK, Django 1.0 is officially supported by Google App Engine and in the article Unleash Django with app-engine-patch the advantages of using App Engine Patch (which allows you to use more Django functionality on Google App Engine) are well described. However the documentation of App Engine Patch is lacking some detailed description on how to set this up this locally. So I decided to write this small tutorial, in which I will guide you setting up Google App Engine SDK with App Engine Patch on an Ubuntu machine.

Why Ubuntu and not Windows?

For me this is a clear-cut choice. I have stepped away from Windows about a year ago after I tried to use Windows Vista Business edition for 8 months and was almost ready to throw the computer out of the building. I have used Windows most of the last 15 years I have been working on computers but in the last few years I saw that Linux is finally able to replace most, if not all, functionalities I require/need from an operating system. And since I also like the open source movement, for me switching to Linux made sense.

First the Debian distribution was my preferred choice but in the last 2 years Ubuntu has become really user friendly (offering a great user interface to Linux and frequent updates). In addition Linux operating system are especially great if you need a web development environment (although it may be challenging at times with the more graphical aspects of web development, like Flash or SilverLight). If you haven’t done recently already, I recommend you to give Linux a try! Please note that most of the steps described below can be applied to most other Linux distributions as well.

Before we start…

What you will need on Ubuntu for this tutorial are:

• A Terminal (which you can find under ‘Main menu > Applications > Accessories > Terminal’)
• A Google App Engine account (apply)
• Google App Engine SDK, Python version (download)
• App Engine Patch (download)
• Python 2.5 (which is available in the Ubuntu repository)

That is basically it, no more is needed :)

Setting Up a Google App Engine Account

In order to be able to use Google App Engine, we need to set up a free account. If you haven’t done this yet I recommend you do so by going to http://appengine.google.com/ and sign in with your Google Account (you will need to create one if you don’t have one yet).

Once logged in, you have to option to ‘Create an Application’ (see button at the bottom of the page). Click the button to create an application and fill in the form. Please note that you can not change the name (Application Identifier) after you have chosen it, nor can you delete it. Also currently you can only create a maximum of 10 applications, so I recommend you create just one for testing purposes (e.g. username-test).

After you are have created the application feel free to browse a little bit through the online admin interface. This is where you will be able to monitor the performance of your application once it has gone live.

Setting up Google App Engine

We can set up Google App Engine in several different ways. Most of the set up requires you to just download the SDK and unzip it. However for App Engine Patch we want to do go one step further. We want to register it in our PATH so we can access it from anywhere else on the computer.

In order to do all of this, first download the Google App Engine SDK (you need to go for the Linux download!) and unzip it into your home directory (one of the ways you can do this is by right-clicking on the zip-file and click on ‘Extract here’).

Unzipping the SDK will create a new sub directory called google_appengine, with the SDK files in it. Note that if all user information is stored under /home/<your-username>/ then after unzipping the SDK should be accessible here:

/home/<your-username>/google_appengine/

in my case this would be:

/home/fili/google_appengine/

Now we want to make sure we all the files have the correct access rights. We could go very specific into detail here and give different file-types different access permissions or we could just do it simple. I choose for the later, so please open a terminal (you can find this in your main menu, under Applications and Accessories). Once you open the terminal you should be in your home directory, under your user account. To verify this, type: pwd. This will print out the current path you are in (see also the screenshot below).

Now type ls and verify that you have the sub directory google_appengine there.

To make sure the access permissions are correct type the following command:

chmod -R 750 ~/google_appengine/

This will set all the permissions to something we can access. Now we need to make sure we can actually access the SDK from anywhere. In order to do this we need to add the sub directory to the environment PATH. In your terminal type:

pico ~/.bashrc

Don’t worry if the file does not exist yet or if it is full of stuff. Once you have opened the file, find the first or second white-line, and add the following lines:

# set path
PATH=$PATH:$HOME/google_appengine
export PATH

Now close and save this by clicking Control-O (this will save the new lines) and Control-X (this will close the nano editor). After this you need to log out of your Ubuntu session and log in again.

After you logged out and in again, you can verify this all worked by opening another terminal and typing:

echo $PATH

This should print something similar to the screenshot below (note the /home/fili/google_appengine at the end of the line.

The hardest part has been done now ;)

Setting Up Python2.5

You probably already have Python installed on your machine but this may be the wrong version. In order to work with App Engine Patch and Google App Engine SDK we need to make sure we all use the same version of Python, for which Python 2.5 is currently the best choice.

You can see which version is primary set up on your computer by opening a terminal and type python2.5. You should then get a screen like this (Control-D or typing exit() will get you out of this screen again):

If you get an error message that Python can not be found, it means that it is not yet installed.

If you don’t have Python 2.5 installed, you will need to install it. Make sure you have an internet connection and type:

sudo apt-get update

This make sure you have the latest repository lists available. Then type this:

sudo apt-get install python2.5

Select ‘Yes’ if asked if you want to proceed and this will install Python version 2.5 on your machine. After this process has been completed, try typing again python2.5.

Setting Up App Engine Patch

We are going to set up the App Engine Patch on our Desktop, but you can put it anywhere else on the computer.

First download the latest version of App Engine Patch to your Desktop and unzip it (similar as how you unzipped the Google App Engine SDK). A new sub directory will be created called ‘app-engine-patch-sample’. You can rename this sub directory to the name of your application (in my case: ‘fili-test’).

Before we can do anything else we need to change a one small settings in app.yaml. Open a terminal and type:

cd ~/Desktop/<your-application-name>/

For me this would translate to:

cd ~/Desktop/fili-test/

Now type:

pico app.yaml

Change the name on the first line to your application name and save the changes (Control-O) and exit the editor (Control-X):

Now your App Engine Patch example folder is associated with your Application Identifier. Now you can run the Google App Engine SDK with your App Engine Patch locally by typing (inside the fili-test subdirectory):

python2.5 manage.py runserver

This will start the local development server (Control-C will allow you to stop the development server again).

If you now open your browser on http://localhost:8000/ you can see the development server running:

That is it. You are done! Now you can start developing web applications using the powerful Django framework on Google App Engine. I recommend you to also browse through these resources about Django and Google App Engine:

• Google App Engine Articles
• Django (official homepage)
• Google App Engine SDK Getting Started Guide
• Google App Engine Documentation (Python)

If you noticed any inaccuracies/errors or you are missing any steps or are running into problems, do leave a comment below!