In this lab, you explore Google App Engine using the Bookshelf sample application. Bookshelf uses Google Cloud Datastore to store data persistently. You deploy the application to the App Engine standard runtime environment, and then you test saving data to Cloud Datastore.

What you need

To complete this lab, you need:

Access to a supported Internet browser:

A Google Cloud Platform project

What you learn

In this lab, you:

In this lab, you explore both Google App Engine and Google Cloud Datastore using the Bookshelf sample application. App Engine is a managed computing environment that lets you focus on writing and running code. As you see in this lab, you do not need to create, configure, or manage any servers, storage, or networks to get started. App Engine handles all of the web traffic generated by your users and automatically scales to meet changes in traffic levels.

Bookshelf is a simple Python web application that lets users create and manage a list of books. The application uses the Flask web microframework to coordinate reading and writing to storage. You can also use a variety of other frameworks to build Python applications on App Engine, including webapp2, and Django.

This version of Bookshelf uses Cloud Datastore to persistently store book data. Google Cloud Datastore is a NoSQL document database, and compliments App Engine through automatic scaling, high performance, and ease of application development.

As you observe in this lab, Bookshelf uses a programming design pattern called model-view-controller, separating the concerns of storage, business logic, and user interface (or view). This simplifies the process of swapping Cloud Datastore, for an alternative service such as Cloud SQL. You can even build, configure, and substitute your own custom storage solution, such as MongoDB to work with Bookshelf. You can find detailed instructions on customizing Bookshelf in the getting started on Google Cloud Platform guide for Python. Tutorials are also available for other programming languages; choose from the list on the Google Cloud Platform Documentation home page.

The following diagram illustrates the high-level components and resources that make up the version of Bookshelf you deploy in this lab.

You also make use of a number of Google Cloud Platform services and features in this lab to assist with the development process. Each Google Cloud Platform project supports Git-compatible Google Cloud Source Repositories that you can use to manage the code for your application.

You also use Google Cloud Shell, a managed command-line environment, to commit code to your repository and deploy code to App Engine. Cloud Shell provides access to many of the tools and utilities typically required to manage Google Cloud Platform projects, including the Cloud SDK you use in this lab. Finally, you use the Google Cloud Platform Console to access your application, and to review data stored in Cloud Datastore.

In this section of the lab, you use Google Cloud Shell to clone a Github repository and to populate a Cloud Source repository with your application source code.

To clone and populate the repository:

Step 1

Open the Google Cloud Platform Console, and if necessary, select the cp100 project.

Step 2

In the Cloud Platform Console navigation pane, click Tools > Source Repositories > Source Code.

Step 3

Click Repositories.

Step 4

If you already have a repository called default, skip to step 6. If not, click CREATE REPOSITORY.

Step 5

In the ‘Create New Repository' dialogue:

Step 6

In the top right corner of the console window, click the Activate Google Cloud Shell button ().

You can use Cloud Shell to:

If a box titled "Google Cloud Shell" appears, read its contents to learn more about Cloud Shell, then dismiss it by clicking Start Cloud Shell.

Step 7

All of the code you need for this course is available in a single repository, which you copy to the source code repository in your project.

You use a local clone of your repository in Cloud Shell to deploy and manage the Google Cloud Platform services and resources in your project.

Type the following command to create a directory for the repository.

mkdir cp100

Step 8

Type the following command to change to the cp100 directory.

cd cp100

Step 9

Each Google Cloud Platform project comes with a single Cloud Source Repository called ‘default', which is currently empty. Type the following command to clone your default repository.

gcloud source repos clone default

The output describes the progress of the clone operation and notes that your repository is currently empty.

Step 10

Type the following command to change to the default directory.

cd default

Step 11

The code for this course is hosted on GitHub. Type the following command to pull the code into your empty project repository.

git pull  https://github.com/GoogleCloudPlatformTraining/cp100-bookshelf

The output confirms that the code has been downloaded to your local repository.

Step 12

Type the following command to push your copy of the code to your project repository.

git push origin master

The output displays the progress of the push to the default Cloud Source Repository in your project.

Step 13

You can now inspect your copy of the code using the Cloud Platform Console.

In the console, click Source Code, and verify you are using the default repository.

You are presented with a list of directory and file names that make up the source code for this course. All of the code required for each of the individual labs is contained in a separate directory.

The remainder of the files listed contain supporting documentation for the original GitHub source code repository:

In the next section, your investigate the source code for this lab in the app-engine directory.

Step 14

Leave both the Cloud Platform Console and Cloud Shell windows open.

Before you deploy the Bookshelf application, it is useful to review some of the code involved in making it work.

To review the code:

Step 1

Return to the Source Code browser in the Cloud Platform Console and click the app-engine folder.

You are presented with a list of directory and file names that make up the source code for this lab.

Most of the application code can be found in the bookshelf directory. You explore most of the code in this repository throughout the remainder of this lab.

Step 2

Click app.yaml.

An App Engine app.yaml configuration file includes a variety of configuration data as required, and optional elements, used to deploy and manage the behavior of your application.

Note in particular, on line 19 that the application runtime is set to Python version 2.7.

Also note, that lines 23 through 25 define the only script handler for this application, that describes how all requests to the application (/.* indicates all requests), should be handled by main.app. A mapping typically defines a URL pattern to match, and the script to be executed. You examine the source code for main.py in the next step.

Step 3

Click the dropdown menu between app-engine and app.yaml and choose main.py.

Notice that this file simply imports the bookshelf code and loads any relevant configuration data into the application.

The file also includes some code used to allow the application to run locally using the development server included with the App Engine SDK.

Step 4

Click / > app-engine > config.py.

This file is used to manage configuration data that is specific to your project and copy of the application. You make changes to this file later in the course but do not need to make any changes to it in this lab.

Step 5

Click / > app-engine > bookshelf.

You are presented with another list of directory and file names that make up the source code for the Bookshelf application.

Step 6

Click crud.py to examine the file.

This file acts as a controller layer and includes a number of functions that coordinate create, read, update, delete operations for the Bookshelf application.

Examine the list() function on lines 22 through 32. Notice that the code doesn't include any direct reference to the type of storage being used. This code abstracts away the specific operations required to read and write from the chosen storage system and passes data between the HTML ‘view' layer, and the storage model. In this lab, you use Cloud Datastore to store data relating to book entries you create in Bookshelf. One advantage of this loosely coupled programming model, is that it is simpler to substitute Cloud Datastore for another storage service such as Cloud SQL during development.

Later in the lab, and after you have deployed and tested the Bookshelf application, you examine the Cloud Datastore code.

Step 7

Leave the Cloud Platform Console and Cloud Shell windows open.

Install all required third-party libraries and dependencies to the local clone of your repository on Cloud Shell. Deploy the application to App Engine using the Cloud SDK and then use the Cloud Platform Console to test the application.

To deploy Bookshelf:

Step 1

Return to Cloud Shell, and type the following command to change to the directory containing the code for this lab.

cd ~/cp100/default/app-engine

Step 2

In addition to the code you copied from GitHub, you also need to install a number of third-party libraries that the Bookshelf application uses. If you would like to see a list of the libraries you need for this lab, type the following command to view the contents of the requirements.txt text file.

cat requirements.txt

The file lists package names and version numbers that you install in the next step.

Step 3

You use the pip command to install Python packages listed as requirements. The pip utility is already installed in Cloud Shell. Type the following command to install the packages and dependencies required for this lab into the lib directory.

pip install -r requirements.txt -t lib

The output displays the progress of the installations.

Step 4

Once deployed to App Engine, the libraries you installed in the previous step are loaded from the lib directory using the code in appengine_config.py. App Engine automatically loads this file when a new instance of your application is started. Type the following command to view the contents of appengine_config.py.

cat appengine_config.py

The vendor subpackage is imported from the google.appengine.ext package on line 7. This is then used on line 11 to add the contents of the lib directory and make it available for importing in the Bookshelf application.

Step 5

You are now ready to deploy the Bookshelf application to App Engine. You use the gcloud command-line utility that is already installed in Cloud Shell to manage your App Engine application. Type the following command to deploy the application.

gcloud app deploy

The system asks you into which GCP region you want to deploy your application.

Please choose the region where you want your App Engine application located:

[1] europe-west2 (supports standard and flexible)

[2] us-east1 (supports standard and flexible)

[3] us-east4 (supports standard and flexible)

[4] asia-northeast1 (supports standard and flexible)

[5] asia-south1 (supports standard and flexible)

[6] australia-southeast1 (supports standard and flexible)

[7] southamerica-east1 (supports standard and flexible)

[8] us-central (supports standard and flexible)

[9] europe-west3 (supports standard and flexible)

[10] europe-west (supports standard and flexible)

[11] cancel

Please enter your numeric choice:

Enter a choice, using its number in the list presented, that is geographically close to you.

You are asked to confirm that you want to proceed with the deployment:

Do you want to continue (Y/n)?

Type Y and press return.

The output displays the progress of the deployment.

The deployment has successfully completed once you see the following message.

Deployed service [default] to [https://<project-id>.appspot.com]

Step 6

Type the following command to quit Cloud Shell.

exit

Step 7

You can now visit and test the deployed Bookshelf application.

In the Cloud Platform Console, click Compute > App Engine.

The App Engine Dashboard loads.

Step 8

In the top right-hand corner of the Dashboard, click the link to your deployed application. The link takes the format:

<project-id>.appspot.com

The Bookshelf application loads in a new browser tab.

Step 9

Leave all browser tabs open.

A kind in Cloud Datastore is roughly equivalent to a table in a relational database. Kinds are used to categorize entities for queries.

Data objects in Google Cloud Datastore are known as entities. An entity has one or more named properties (which are like fields in a relational database). Each property can have one or more values. Entities are identified by a unique key and are akin to rows in a relational database. Entities of the same kind need not have the same properties. These unique characteristics imply a different way of designing and managing data to take advantage of the ability to scale automatically.

Cloud Datastore also organizes data into entity groups. An entity group consists of a root entity and all of its descendants. Applications typically use entity groups to organize highly related data to achieve strong consistency and to enforce transactionality. For example, an application could use an entity group to store data about one product, or one user profile.

The Bookshelf data model for Cloud Datastore is illustrated by the following diagram. Note that the simple data model used in Bookshelf does not make use of entity groups.

Generate some simple test data in the Bookshelf application to verify that it is working as expected. Investigate the Cloud Datastore test data using the Cloud Platform Console and review related code.

Step 1

Return to the Bookshelf application in your web browser.

Bookshelf is a simple web application that allows users to add details of books to a database and then list, view, edit and delete entries from the bookshelf.

When Bookshelf is first deployed, there is no test data included. To begin exploring the application click Add book.

Step 2

On the ‘Add book' page:

A page loads with the details you recorded for the new book, in addition to a placeholder image.

Step 3

Return to the Cloud Platform Console browser tab and click Storage > Datastore.

The Cloud Datastore Entities page loads.

Notice that an entity is now listed in Cloud Datastore that includes the book details you entered earlier in this section. The entity includes a unique numerical key that you did not specify. This is used to locate this entity. Next, you explore the code that generates the key.

Step 4

Click Tools > Source Repositories > Source Code.

Step 5

Click / > app-engine > bookshelf > model_datastore.py.

This file includes code used to read and write data using Cloud Datastore. The standard Python 2.7 App Engine runtime includes support for the NDB client library, that in turn supports automatic caching, sophisticated queries, and atomic transactions in Cloud Datastore.

The NDB client library is imported on line 17 and is used to define a model for book entities you create in the application. The Book class is defined on lines 28 through 32 and includes a series of string properties that correspond to the form fields you populated when testing the application.

Creating and updating book entities is carried out by the update() function. If the application is creating a new book then the key is not yet known and an id is automatically generated by the Book class on line 87. If a book is being updated then the id is passed to the function and used to generate the corresponding key on line 84. The key is then used to retrieve the corresponding book entity on line 85.

Step 6

Close all browser tabs.

There is no need for you to remove the resources used in this lab.

©Google, Inc. or its affiliates. All rights reserved. Do not distribute.