Running Django in the App Engine Flexible Environment

It's easy to get started developing Django apps that run in the Google App Engine flexible environment, and because the apps you create will run on the same infrastructure that powers all of Google's products, you can be confident that they will scale to serve all of your users, whether there are a few or millions of them.

This tutorial assumes you are familiar with with Django web development. It walks you through deploying the official Django tutorial app, Writing your first Django App. It's a good idea work through that tutorial before this one, especially if you are new to Django development. The app's models represent polls that contain questions, and you can interact with the models using the Django admin console.

This tutorial requires Python 2.7 or 3.4.

Before you begin

Check off each step as you complete it.

  1. check_box_outline_blank check_box Create a project in the Google Cloud Platform Console.
    If you haven't already created a project, create one now. Projects enable you to manage all Google Cloud Platform resources for your app, including deployment, access control, billing, and services.
    1. Open the Cloud Platform Console.
    2. In the drop-down menu at the top, select Create a project.
    3. Click Show advanced options. Under App Engine location, select a United States location.
    4. Give your project a name.
    5. Make a note of the project ID, which might be different from the project name. The project ID is used in commands and in configurations.
  2. check_box_outline_blank check_box Enable billing for your project, and sign up for a free trial.

    If you haven't already enabled billing for your project, enable billing now, and sign up for a free trial. Enabling billing allows the application to consume billable resources such as running instances and storing data. During your free trial period, you won't be billed for any services.

  3. check_box_outline_blank check_box Install the Google Cloud SDK.

    If you haven't already installed the Google Cloud SDK, install and initialize the Google Cloud SDK now. The SDK contains tools and libraries that enable you to create and manage resources on Google Cloud Platform.

  4. check_box_outline_blank check_box Enable APIs for your project.

    This takes you to the Cloud Platform Console and automatically enables the APIs used by this tutorial. The APIs used are: Google Cloud SQL API.

Download and run the app

After you've completed the prerequisites, you can download and deploy the Django sample app. The following sections guide you through configuring, running, and deploying the sample.

Clone the Django sample app

The code for the Django sample app is in the Google Cloud Platform Python Samples repository on GitHub.

Clone the repository to your local machine:

git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git

Go to the directory that contains the sample code:

Linux/Mac OS X

cd python-docs-samples/appengine/flexible/django_cloudsql

Windows

cd python-docs-samples\appengine/flexible\django_cloudsql

Alternatively, you can download the sample as a zip and extract it.

Setting up your local environment

When deployed, your application uses the Cloud SQL Proxy that is built in to the App Engine environment to communicate with your Cloud SQL instance. However, to test your application locally, you must install and use a local copy of the Cloud SQL Proxy in your development environment.

Learn more about the Cloud SQL Proxy.

To perform basic administrative tasks on your Cloud SQL instance, you can use the PostgreSQL Client.

Install the SQL proxy

Download and install the Cloud SQL Proxy. The Cloud SQL Proxy is used to connect to your Cloud SQL instance when running locally.

Linux 64-bit

  1. Download the proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy
    
  2. Make the proxy executable:
    chmod +x cloud_sql_proxy
    

Linux 32-bit

  1. Download the proxy:
    wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy
    
  2. Make the proxy executable:
    chmod +x cloud_sql_proxy
    

OS X 64-bit

  1. Download the proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64
    
  2. Make the proxy executable:
    chmod +x cloud_sql_proxy
    

OS X 32-bit

  1. Download the proxy:
    curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386
    
  2. Make the proxy executable:
    chmod +x cloud_sql_proxy
    

Windows 64-bit

Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x64.exe and select "Save link as..." to download the proxy, renaming it to cloud_sql_proxy.exe.

Windows 32-bit

Right-click https://dl.google.com/cloudsql/cloud_sql_proxy_x86.exe and select "Save link as..." to download the proxy, renaming it to cloud_sql_proxy.exe.
If your operating system is not included here, you can also compile the proxy from source.

Create a Cloud SQL instance

  1. Create a Cloud SQL for PostgreSQL instance.

    Name the instance polls-instance or similar. It can take a few minutes for the instance to be ready. After the instance is ready, it should be visible in the instances list.

  2. Now use the Cloud SDK from command line to run the following command. Copy the value shown for connectionName for the next step.
    gcloud sql instances describe [YOUR_INSTANCE_NAME]

    The connectionName value is in the format [PROJECT_NAME]:[REGION_NAME]:[INSTANCE_NAME].

Initialize your Cloud SQL instance

  1. Start the Cloud SQL Proxy using the connectionName from the previous step.

    Linux/Mac OS X

    ./cloud_sql_proxy -instances="[YOUR_INSTANCE_CONNECTION_NAME]"=tcp:5432

    Windows

    cloud_sql_proxy.exe -instances="[YOUR_INSTANCE_CONNECTION_NAME]"=tcp:5432

    Replace [YOUR_INSTANCE_CONNECTION_NAME] with the value of connectionName that you recorded in the previous step.

    This step establishes a connection from your local computer to your Cloud SQL instance for local testing purposes. Keep the Cloud SQL Proxy running the entire time you test your application locally.

  2. Next you create a new Cloud SQL user and database.

    CONSOLE

    1. Create a new database using the Cloud Platform Console for your Cloud SQL instance polls-instance. For example, you can use the name polls.
    2. Create a new user using the Cloud Platform Console for your Cloud SQL instance polls-instance.

    POSTGRES CLIENT

    1. In a separate command-line tab, install the Postgres client.
      sudo apt-get install postgresql
      
    2. Use the Postgres client or similar program to connect to your instance. When prompted, use the root password you configured.
      psql --host 127.0.0.1 --user postgres --password
      
    3. Create the required databases, users, and access permissions in your Cloud SQL database using the commands below. Replace [POSTGRES_USER] and [POSTGRES_PASSWORD] with your desired username and password.
      CREATE DATABASE polls;
      CREATE USER [POSTGRES_USER] WITH PASSWORD '[POSTGRES_PASSWORD]';
      GRANT ALL PRIVILEGES ON DATABASE polls TO [POSTGRES_USER];
      GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO [POSTGRES_USER];
      

Configure the database settings

  1. Open mysite/settings.py for editing.

  2. Replace <your-database-user> and <your-database-password> with the username and password you created previously.

  3. Run the following command from command line. Copy the outputted connectionName value for the next step.

    gcloud beta sql instances describe [YOUR_INSTANCE_NAME]
    
  4. Replace <your-cloudsql-connection-string> with connectionName from the previous step.

  5. Close and save settings.py.

Run the app on your local computer

  1. To run the Django 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.

  2. Create an isolated Python environment, and install dependencies:

    Linux/Mac OS X

    virtualenv env
    source env/bin/activate
    pip install -r requirements.txt
    

    Windows

    virtualenv env
    env\scripts\activate
    pip install -r requirements.txt
    

  3. Run the Django migrations to set up your models:

    python manage.py makemigrations
    python manage.py makemigrations polls
    python manage.py migrate
    
  4. Start a local web server:

    python manage.py runserver
    
  5. In your web browser, enter this address:

    http://localhost:8000
    

You should see a simple webpage with the following text: "Hello, world. You're at the polls index." The sample app pages are delivered by the Django web server running on your computer. When you're ready to move forward, press Ctrl+C to stop the local web server.

Use the Django admin console

  1. Create a superuser:

    python manage.py createsuperuser
    
  2. Run the main program:

    python manage.py runserver
    
  3. Enter this address in your web browser. To log on to the admin site, use the username and password you created when you ran createsuperuser.

    http://localhost:8000/admin
    

Deploy the app to the App Engine flexible environment

  1. When the app is deployed to Cloud Platform, it uses the Gunicorn server. Gunicorn doesn't serve static content, so the app uses Google Cloud Storage to serve static content.

    Create a Cloud Storage bucket and make it publically readable. Replace <your-gcs-bucket> with a bucket name of your choice. For example, you could use your project ID as a bucket name:

    gsutil mb gs://<your-gcs-bucket>
    gsutil defacl set public-read gs://<your-gcs-bucket>
    
  2. Gather all the static content locally into one folder:

    python manage.py collectstatic
    
  3. Upload the static content to CloudStorage:

    gsutil rsync -R static/ gs://<your-gcs-bucket>/static
    
  4. In mysite/settings.py, set the value of STATIC_URL to this URL:

    http://storage.googleapis.com/<your-gcs-bucket>/static/
    
  5. In app.yaml, replace <your-cloudsql-connection-string> with the value of connectionName outputted from the following command:

    gcloud beta sql instances describe [YOUR_INSTANCE_NAME]
    
  6. Enter this command to deploy the sample:

    gcloud app deploy
    

    Wait for the message that notifies you that the update has completed.

See the app run in the cloud

In your web browser, enter this address:

https://<your-project-id>.appspot.com

This time, your request is served by a web server running in the App Engine flexible environment.

This command deploys the application as described in app.yaml and sets the newly deployed version as the default version, causing it to serve all new traffic. As the app deploys, you might see several repeated messages while the platform checks whether the app is serving. This is normal. Wait for the message that notifies you that the update of the app is complete.

If you update your app, you can deploy the updated version by entering the same command you used to deploy the app the first time. The new deployment creates a new version of your app and promotes it to the default version. The older versions of your app remain, as do their associated VM instances. Be aware that all of these app versions and VM instances are billable resources. For information about deleting or stopping your VM instances, see Cleaning up.

Production

When you are ready to serve your content in production, make the following configuration change:

  1. In mysite/settings.py, change the DEBUG variable to False.

Understanding the code

The Django sample app was created using the standard Django tooling. These commands create the project and the polls app:

django-admin startproject mysite
python manage.py startapp polls

The settings.py contains the configuration for your SQL database:

DATABASES = {
    'default': {
        # If you are using Cloud SQL for MySQL rather than PostgreSQL, set
        # 'ENGINE': 'django.db.backends.mysql' instead of the following.
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'polls',
        'USER': '<your-database-user>',
        'PASSWORD': '<your-database-password>',
    }
}
# In the flexible environment, you connect to CloudSQL using a unix socket.
# Locally, you can use the CloudSQL proxy to proxy a localhost connection
# to the instance
DATABASES['default']['HOST'] = '/cloudsql/<your-cloudsql-connection-string>'
if os.getenv('GAE_INSTANCE'):
    pass
else:
    DATABASES['default']['HOST'] = '127.0.0.1'

Also in settings.py, you can set the value of STATIC_URL to specify how the app serves static content:

# Fill in your cloud bucket and switch which one of the following 2 lines
# is commented to serve static content from GCS
# STATIC_URL = 'https://storage.googleapis.com/<your-gcs-bucket>/static/'
STATIC_URL = '/static/'

The app.yaml file contains configuration information for deployment to the flexible environment.

runtime: python
env: flex
entrypoint: gunicorn -b :$PORT mysite.wsgi

beta_settings:
    cloud_sql_instances: <your-cloudsql-connection-string>

runtime_config:
  python_version: 3

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...