Installing and Running Google App Engine on a Macintosh System: Appendix C - Using Google App Engine

Download the appropriate install package for the Google App Engine SDK from http://code.google.com/appengine/downloads.html, as shown in Figure C.1, “Downloading Google Application Engine”.

Figure C.1. Downloading Google Application Engine

Download the Mac OS X installer. It should automatically mount as a virtual drive (Figure C.2, “The App Engine Installer”).

Figure C.2. The App Engine Installer

Drag the GoogleAppEngineLauncher to the Applications folder on your hard drive. This step copies Google App Engine and installs it as an application on your system. Once this is done, you can eject the virtual drive.

Navigate to the /Applications folder on your main disk, find the AppEngineLauncher icon, and launch it. You may need to scroll to the bottom of your screen to see the App Engine icon.

Click Accept or Open in any dialog box that asks whether it is OK to launch, as shown in Figure C.3, “Installing Google App Engine”.

Figure C.3. Installing Google App Engine

When the Engine launches for the first time, it asks if you want to make Command Symlinks, as shown in Figure C.4, “Making symbolic links”.

Figure C.4. Making symbolic links

Click OK. This step will allow you to run App Engine from the command line later. You will have to type an administrator password to make the links.

At this point, you can actually close the App Engine Launcher—you will run the application from the command-line interface (the Terminal application) instead of using the Launcher user interface.

Now you need to create a simple application. We could use the graphical launcher to make our application, but instead we will do it by hand to give you a better sense of what is going on.

Make a folder for your Google App Engine applications. I am going to name the folder on my Macintosh Desktop apps. The path to this folder is: /Users/csev/Desktop/apps—obviously your path will use your account name instead of mine. Then make a subfolder in within apps called ae-01-trivial: /Users/csev/Desktop/apps/ae-01-trivial.

Create a file called app.yaml in the ae-01-trivial folder with the following contents:

application: ae-01-trivial
version: 1
runtime: python
api_version: 1

handlers:
- url: /.*
  script: index.py

Then create a file in the ae-01-trivial folder called index.py, with three lines of Python:

print 'Content-Type: text/plain'
print ''
print 'Hello there Chuck'

Then start the Terminal program, which can be found under Applications→Utilities→ Terminal. Use the cd command to navigate to the apps directory, as shown in Figure C.5, “Navigating to the apps directory”.

Figure C.5. Navigating to the apps directory

When you are in the apps directory, start the Google App Engine Web Server and run your application using the following command:

/usr/local/bin/dev_appserver.py ae-01-trivial

You will be asked if you want App Engine to check for updates (type y); after a few messages, the server will start up, as shown in Figure C.6, “Starting the application server”.

Figure C.6. Starting the application server

The last line tells you which port your application is running on and what URL you should use to access your application; in this case, our application is at http://localhost:8080.

Paste http://localhost:8080 into your browser and you should see your application, as shown in Figure C.7, “Your Google application”.

Figure C.7. Your Google application

Just for fun, edit the index.py to change the name “Chuck” to your own name and refresh the page in the browser to verify your updates.

With two files to edit, there are two general categories of errors that you may encounter. The first common error is making a mistake in your app.yaml file. If you make a mistake on the app.yaml file, App Engine will not start, and you will see an error as shown in Figure C.8, “Error in app.yaml”.

Figure C.8. Error in app.yaml

In this instance, the mistake is an incorrectly indented final line in the app.yaml (line 8).

When you make a mistake in the app.yaml file, you must the fix the mistake and attempt to start the application again.

The second type of error is in the index.py file. If you make a syntax error in the index.py file, the error will appear in your browser. The error looks terrible and looks like everything went wrong, as shown in Figure C.9, “Syntax error”.

Figure C.9. Syntax error

Do not be alarmed! Ignore most of the output and scroll to the very bottom of the error output. The error you need to see is likely to be the very last line of the output—in this case, I made a Python syntax error on the first and only line of our one-line index.py file, as shown in Figure C.10, “Finding the syntax error”.

Figure C.10. Finding the syntax error

See also http://en.wikipedia.org/wiki/Stack_trace for more information.

If you make a mistake in a file like index.py, you can just fix the file and refresh your browser—there is no need to restart the server.

To shut down the server, go into the window where you started the server and press Ctrl-C to abort the server. You should see a message that says something like “Server interrupted by user, terminating” and the server will shut down. You can start it back up using the dev_appserver.py command again. When the server is shut down, navigating to http://localhost:8080 will fail because there is no software running on and listening to port 8080.