App Engine Series #2: Organizing Your Project

Important: As of July 2015, this tutorial no longer works, as App Engine has shut down the Master/Slave Data Store that the application uses. We are keeping it online for reference purposes and you can still download the code, but it needs to be converted to the newer High Availability Data Store to work.

In this second part of our App Engine series, we will lay down the directory structure of our application and create the needed configuration files. You can find the first part here.

The Directory Structure

Every App Engine application requires a number of configuration files to be present in the root folder. In our case these are app.yaml, index.yaml and cron.yaml (more on these in a moment). The rest of the directory structure is up to the programmer.

To keep things clean, our dashboard app employs the following organization:

You can see a number of folders here:

• The assets folder contains images, stylesheets and js files (each in their subfolder);
• The config folder contains a python file with a few configuration options, including the URL of the webpage to be fetched, and the title of the application. This is independent from the yaml config files, which are used by App Engine;
• The models, views and controllers folders contain Python source files according to the MVC pattern.

main.py is the first file that is accessed when a new request is made. It routes the requests to the appropriate controllers, as you will see in the next part of the series.

The Configuration Files

As you saw in the first part, when deploying your own copy of the uptime dashboard, you had to edit a number of files. These are App Engine's configuration files, which define the language that your application uses, its unique identifier and version.

These configuration values are written in the yaml file format. This format is designed for easy data serialization, and represents many of the data types you would normally find in a programming language - numeric and associate arrays, strings and numbers, which makes it perfect for storing configuration data.

app.yaml

application: tutorialzine-dashboard
version: 1
runtime: python
api_version: 1

builtins:
- datastore_admin: on

handlers:

- url: /assets
  static_dir: assets

- url: /favicon.ico
  static_files: assets/img/favicon.ico
  upload: assets/img/favicon.ico

- url: /crons/.*
  script: main.py
  login: admin

- url: /generate-test-data/
  script: main.py
  login: admin

- url: .*
  script: main.py

app.yaml is the main configuration file in your application. It is automatically created and populated by the app engine launcher when you create a new app. You can read more about it in App Engine's documentation.

The first two lines contain the application identifier and version. The identifier is assigned to your application when you add it from appengine.google.com. App Engine can also manage multiple versions of your app, specified by the version attribute. They are ready to deploy from the control panel and you can easily rollback an older one if you detect a problem.

The builtins directive enables your app to display the Datastore Administration screen in App Engine's control panel, which is useful in monitoring and deleting data.

Lastly you can see the handlers, which route an URL (represented by a regular expression) to the script that handles it. You need to specify your static files (everything that differs from a python script, like images, css and js files) using either the static_files or static_dir directives. Above I've declared that all requests to dashboard.tutorialzine.com/assets should be routed to the assets folder.

You can also optionally specify that a URL is limited to the application administrator. Above I've used this option to declare that the /crons/ URL is accessible only by the app admins and the cron service, to prevent people from triggering the cron scripts (more on that in the next part of the series).

crons.yaml

cron:

- description: Five minute ping
  url: /crons/5min/
  schedule: every 5 minutes

- description: Daily averages
  url: /crons/1day/
  schedule: every day 00:00

crons.yaml configures the cron service. The fragment above tells the service to execute /crons/5min/ once every five minutes and the other URL - /crons/1day/ once per day at midnight. These URLs are going to be accessed exactly as a regular http request, meaning that you do not need any special preparations to execute a certain address from cron.

The last file - index.yaml is created automatically by the app launcher and in it you define the indexes that are used by the datastore. Indexes are important as they speed up your queries which is also the reason why they are created automatically for simple queries (in which you select rows based on the value of a single column). Luckily for us, all the queries used in the uptime dashboard are of the simple kind, so there is no need to modify index.yaml.

With this we have successfully configured your new app engine application!

Parting Words

Stay tuned for the next part of the series, where we will be writing some real python code! In the meantime you can subscribe to our feed and follow us on twitter for updates.

Continue to part three.