Getting Started with Flask on App Engine Standard Environment

This guide is designed to help you learn how to develop and deploy basic Python 2.7 applications that run on the Google App Engine Standard Environment. This guide is intended for use by those new to Google App Engine, its related services, and in particular, using App Engine with the Python language. For that reason, the guide provides deeper explanations for each task than what is found in the Quickstart guide.

Before you begin

Before you can develop an application:

  1. Create a new Cloud Platform Console project or retrieve the project ID of an existing project from the Google Cloud Platform Console:

    Go to the Projects page

    Tip: Retrieve a list of your existing project IDs with the gcloud command line tool.

  2. Install and then initialize the Google Cloud SDK.

Creating a basic application

This guide uses the Flask web application framework because of its simplicity, ease of use, and extensibility, but the same principles can be applied to any framework that you want to use. This guide teaches you:

  • How to create a basic user comment form that will display the content that the user submits via that form on an HTML template that you create.
  • How to create a basic application that can serve static files, such as CSS or images.

After you have set up your development environment, you can write the code for the application and deploy it to App Engine.

Basic structure of an app project

This guide uses the following structure for the flask-app project:

flask-app project structure

  • app.yaml: Configure the settings of your App Engine application
  • main.py: Write the content of your application
  • static: Directory to store your static files
    • style.css: Basic stylesheet that formats the look and feel of your template files
  • templates: Directory for all of your HTML templates
    • form.html: HTML template to display your form
    • submitted_form.html: HTML template to display the content of a submitted form

Setting up libraries to enable development

By default, the Google App Engine Python 2.7 runtime environment includes the Python standard library, the App Engine libraries, and a few bundled third- party packages. This guide will not explicitly use any runtime-provided libraries, but it will use other third-party libraries. For a complete list of runtime-provided libraries, see the built-in third-party libraries reference.

  1. Create a file named appengine_config.py in the root project directory. When you deploy your application, you can use this file to specify where App Engine should look for third-party libraries:

    
    # [START vendor]
    from google.appengine.ext import vendor
    
    # Add any libraries installed in the "lib" folder.
    vendor.add('lib')
    # [END vendor]
    

  2. Create a file named requirements.txt in the root project directory:

    Flask==0.12.1
    

  3. To run this app on your local computer, you'll need a Python development environment set up, including Python, pip, and virtualenv. Follow these instructions to install on Linux, OS X, or Windows.

  4. Create and enter an isolated Python environment using virtualenv:

    Linux/Mac OS X

    virtualenv env 
    source env/bin/activate

    Windows

    virtualenv env 
    env\scripts\activate

    At the end of the tutorial, you can exit your virtualenv by typing deactivate.

  5. Install dependencies using pip:

    pip install -t lib -r requirements.txt
    

    The -t lib flag copies the libraries into a lib folder, which is uploaded to App Engine during deployment. See Installing a third-party library for more information about the vendoring process.

    The -r requirements.txt flag tells pip to install everything from a requirements.txt file.

Creating the app.yaml file

You can configure your App Engine application's settings in the app.yaml file that you create manually or as part of the creation of your development project. The app.yaml file is a configuration file that tells App Engine how to run your application and how to map URLs to static files and Python modules.

To create the app.yaml file:

  1. Create a file named app.yaml in the root directory of your project.
  2. Add the following lines to the file:

    runtime: python27
    api_version: 1
    threadsafe: true
    
    # [START handlers]
    handlers:
    - url: /static
      static_dir: static
    - url: /.*
      script: main.app
    # [END handlers]
    

More reference information about the app.yaml file can be found in the app.yaml reference documentation.

Creating a request handler for your Flask app

When App Engine receives a web request for your application, it calls the handler script that corresponds to the URL, as described in the application's app.yaml configuration file. The Python 2.7 runtime supports the WSGI standard. WSGI is preferred, and some features of Python 2.7 do not work without it. The configuration of your application's script handlers determines whether a request is handled using WSGI.

The server determines which Python application object to call by comparing the URL of the request to the URL patterns in the app's configuration file. It then calls the application object using the arguments as defined in the WSGI standard. The application object performs actions appropriate to the request, then prepares a response and returns it as a list of strings.

The following request handlers take the information that is submitted in the form in the /templates/form.html file and places that information onto the /templates/submitted_form.html template file:

  1. Create a new file called main.py in the root directory of your application.

  2. Import the Flask framework and the Flask interfaces that you want to use:

    from flask import Flask, render_template, request

  3. Add this line to create an instance of the Flask class and assign it to a variable called app:

    app = Flask(__name__)

  4. Create a request handler that displays a form using the form.html template:

    @app.route('/form')
    def form():
        return render_template('form.html')

    When the user navigates to the /form/ directory within the application, the form.html template that you will create will be displayed.

  5. Create a request handler that handles the information from the submitted form:

    @app.route('/submitted', methods=['POST'])
    def submitted_form():
        name = request.form['name']
        email = request.form['email']
        site = request.form['site_url']
        comments = request.form['comments']
    

    The application stores the form information in the variables that you created here. These variables will allow you to post the data from the form onto the submitted_form.html template that you will create.

You can learn more about how to quickly get started with Flask in the Flask quickstart guide.

You can easily extend the functionality of this form. For example, you can use the Mail API, Mailgun, Mailjet, or SendGrid to send the comments that users submit to yourself or to others.

Setting up Jinja2 templates

Since HTML that is embedded in code can be difficult to maintain, you should use a templating system, storing HTML in a separate file that uses special syntax to specify where the data returned from an application appears. You can use your template engine of choice by bundling it with your application code. For your convenience, App Engine includes the Django and Jinja2 templating engines.

  1. Add the following line to the end of the submitted_form() function:

    return render_template(
        'submitted_form.html',
        name=name,
        email=email,
        site=site,
        comments=comments)

    This line uses the render_template() interface to render the submitted_form.html template with submitted form information.

  2. Create the form.html and submitted_form.html templates:

    1. Create a new folder called templates in your root directory:

      mkdir templates
      
    2. Create form.html in the templates directory of your project:

      <html>
        <head>
          <title>Submit a form</title>
         <link rel="stylesheet" type="text/css" href="/static/style.css">
        </head>
        <body>
          <div id="container">
            <div class="pagetitle">
              <h1>Submit a form</h1>
            </div>
            <div id="main">
              <form method="post" action="{{ url_for('submitted_form') }}">
                <label for="name">Name:</label>
                <input type="text" name="name"><br />
                <label for="email">Email address:</label>
                <input type="email" name="email"><br />
                <label for="site_url">Website URL:</label>
                <input type="url" name="site_url"><br />
                <label for="comments">Comments:</label>
                <textarea name="comments"></textarea><br />
                <input type="submit">
              </form>
            </div>
          </div>
        </body>
      </html>
      

    3. Create submitted_form.html in the templates directory of your project:

      <html>
       <head>
         <title>Submitted form</title>
         <link rel="stylesheet" type="text/css" href="/static/style.css">
       </head>
       <body>
         <div id="container">
           <div class="pagetitle">
             <h1>Form submitted</h1>
           </div>
           <div id="main">
             <p>Thanks for your submission, {{name}}!</p>
             <p>Here's a review of the information that you sent:</p>
             <p>
                <strong>Name</strong>: {{name}} <br>
                <strong>Email</strong>: {{email}} <br>
                <strong>Website URL</strong>: {{site}} <br>
                <strong>Comments</strong>: {{comments}}
             </p>
           </div>
         </div>
       </body>
      </html>
      

To learn more about using templates with Flask and Jinja2, visit the official Flask documentation.

Serving static files

Serving static files is more efficient for some content, such as images, CSS or Flash animations, which aren't generated dynamically when a page is requested.

Create a CSS file and create a handler for it:

  1. Create a new folder called static in your root directory:

    mkdir static
    
  2. Create the style.css file that will modify the look of your template files that you just created. Create the file in the static folder of your project and add the following styling:

    .pagetitle {
        color: #800080;
    }
    

  3. The app.yaml file you created earlier specifies the static directories that contain static files:

    handlers:
    - url: /static
      static_dir: static
    - url: /.*
      script: main.app

    The handlers section defines two handlers for URLs. When App Engine receives a request for a URL beginning with /static, it maps the remainder of the path to files in the static directory, and if an appropriate file is found, the contents of the file are returned to the client.

For more information on URL mapping and other options you can specify in app.yaml, see the app.yaml reference.

Test the application

Test the application using the local development server (dev_appserver.py), which is included with the SDK.

  1. From within the root directory where the app's app.yaml configuration file is located, start the local development server with the following command:

      dev_appserver.py app.yaml
    

    The local development server is now running and listening for requests on port 8080.

    Something go wrong?

  2. Visit http://localhost:8080/form in your web browser to view the app.

Running the local development server (dev_appserver.py)

To run the local development server, you can either run dev_appserver.py by specifying the full directory path or you can add dev_appserver.py to your PATH environment variable:

  • If you installed the original App Engine SDK, the tool is located at:

    [PATH_TO_APP_ENGINE_SDK]/dev_appserver.py
    
  • If you installed the Google Cloud SDK, the tool is located at:

    [PATH_TO_CLOUD_SDK]/google-cloud-sdk/bin/dev_appserver.py
    

    Tip: To add the Google Cloud SDK tools to your PATH environment variable and enable command-completion in your shell, you can run:

    [PATH_TO_CLOUD_SDK]/google-cloud-sdk/install.sh
    

For more information about running the local development server including how to change the port number, see the Local Development Server reference.

Make a change

You can leave the development server running while you develop your application. The development server watches for changes in your source files and reloads them if necessary.

  1. Try it now: Leave the development server running, then edit templates/main.html to change the Submit a form text within the <h1> tags to something else.
  2. Reload http://localhost:8080/form to see the results.

Deploying your application

To upload the app, run the following command from within the root directory of your project where the app.yaml file is located:

gcloud app deploy

Optional flags:

  • Include the --project flag to specify an alternate Cloud Platform Console project ID to what you initialized as the default in the gcloud tool. Example: --project [YOUR_PROJECT_ID]
  • Include the -v flag to specify a version ID, otherwise one is generated for you. Example: -v [YOUR_VERSION_ID]

To learn more about deploying your app from the command line, see Deploying a Python App.

Viewing your application

Open your browser and view your app at http://[YOUR_PROJECT_ID].appspot.com/form.

Support

If you encounter problems during the development of your application, you can get help from technical support and developer communities.

What's next

Send feedback about...

App Engine standard environment for Python