Running Django in the App Engine flexible environment

Django apps that run on the App Engine flexible environment are running on the same infrastructure that powers all of Google's products, which generally improves scalability.

This tutorial assumes you're familiar with Django web development. If you're new to Django development, it's a good idea to work through writing your first Django app before continuing. In that tutorial, the app's models represent polls that contain questions, and you can interact with the models by using the Django admin console.

This tutorial requires Python 3.7 or later.

Before you begin

Sign in to your Google Account.
If you don't already have one, sign up for a new account.
In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to the project selector page
Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.
Enable the Cloud SQL Admin API.
Enable the API

Install and initialize the Cloud SDK.
Note: You can run the gcloud tool in the Cloud Console without installing the Cloud SDK. To run the gcloud tool in the Cloud Console, use Cloud Shell .

Log in to gcloud

Acquire new credentials to use the Cloud SQL Admin API:

gcloud auth application-default login

Downloading and running the app

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

Cloning the Django app

The code for the Django sample app is in the GoogleCloudPlatform/python-docs-samples repository on GitHub.

You can either download the sample as a ZIP file and extract it or 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/macOS

  cd python-docs-samples/appengine/standard_python3/django

Windows

  cd python-docs-samples\appengine\standard_python3\django

Setting up your local environment

When deployed, your app 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 app locally, you must install and use a local copy of the proxy in your development environment.

Learn more about the Cloud SQL Proxy.

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

Installing the Cloud SQL Proxy

Download and install the Cloud SQL Proxy. The Cloud SQL Proxy connects to your Cloud SQL instance when running locally.

Linux 64-bit

Download the Cloud SQL Proxy:

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy

Make the Cloud SQL Proxy executable:
```
chmod +x cloud_sql_proxy
```

Linux 32-bit

Download the Cloud SQL Proxy:

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.386 -O cloud_sql_proxy

Make the Cloud SQL Proxy executable:
```
chmod +x cloud_sql_proxy
```

macOS 64-bit

Download the Cloud SQL Proxy:

curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.amd64

Make the Cloud SQL Proxy executable:
```
chmod +x cloud_sql_proxy
```

macOS 32-bit

Download the Cloud SQL Proxy:

curl -o cloud_sql_proxy https://dl.google.com/cloudsql/cloud_sql_proxy.darwin.386

Make the Cloud SQL 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 Cloud SQL Proxy. Rename the file 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 Cloud SQL Proxy. Rename the file to cloud_sql_proxy.exe.

Cloud SQL Proxy Docker image

For convenience, the Cloud SQL team maintains several container images that contain the Cloud SQL Proxy for use by our customers. For more information about these images, see the Cloud SQL Proxy repo on GitHub. You can pull the latest image to your local machine using Docker with the following command:

docker pull gcr.io/cloudsql-docker/gce-proxy:1.19.1

Other OS

For other operating systems not included here, you can compile the Cloud SQL Proxy from source.

Creating a Cloud SQL instance

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. When the instance is ready, it's visible in the instances list.
Use the Cloud SDK to run the following command where [YOUR_INSTANCE_NAME] represents the name of your Cloud SQL instance:
```
gcloud sql instances describe [YOUR_INSTANCE_NAME]
```
In the output, note the value shown for [CONNECTION_NAME].

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

Initializing your Cloud SQL instance

Start the Cloud SQL Proxy by using the [CONNECTION_NAME] value from the previous step:
Linux/macOS
```
./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 [CONNECTION_NAME] value 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 app locally.
Create a Cloud SQL user and database:
Cloud Console
1. Create a new database by using the Cloud Console for your Cloud SQL instance polls-instance. For example, you can use the name polls.
2. Create a new user by using the Cloud 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 by using the following commands. Replace [POSTGRES_USER] and [POSTGRES_PASSWORD] with the username and password you want to use.
```
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];
```

Configuring the database settings

Open mysite/settings.py for editing.
1. To use MySQL instead of PostgreSQL:
  1. Follow the instructions in the file comments to enable the MySQL database driver.
  2. Open requirements.txt for editing and follow the instructions to add the MySQL database driver to your dependencies.
2. To help set up the connection to the database for both App Engine deployment and local testing, set <your-database-user> and <your-database-password> to the username and password you created previously in the step Creating a Cloud SQL instance
3. Get the values for your instance:
```
gcloud sql instances describe [YOUR_INSTANCE_NAME]
```
4. From the output, copy the connectionName value for use in the next step.
5. Set <your-cloudsql-connection-string> to the connectionName from the previous step.
Close and save settings.py.

Running the app on your local computer

To run the Django app on your local computer, set up a Python development environment, including Python, pip, and virtualenv.

Create an isolated Python environment and install dependencies:

Linux/macOS

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

Windows

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

Run the Django migrations to set up your models:

python manage.py makemigrations
python manage.py makemigrations polls
python manage.py migrate

Start a local web server:
```
python manage.py runserver
```
In your browser, go to http://localhost:8000.
```
http://localhost:8000
```
The page displays the following text: "Hello, world. You're at the polls index." The Django web server running on your computer delivers the sample app pages.
Press Control+C to stop the local web server.

Using the Django admin console

Create a superuser. You need to define a username and password.
```
python manage.py createsuperuser
```
Start a local web server:
```
python manage.py runserver
```
In your browser, go to http://localhost:8000/admin.
```
http://localhost:8000/admin
```
Log in to the admin site using the username and password you used when you ran createsuperuser.

Deploying the app to the App Engine flexible environment

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

Create a Cloud Storage bucket:
1. Create a Cloud Storage bucket and make it publicly 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 Cloud Storage:
```
gsutil rsync -R static/ gs://<your-gcs-bucket>/static
```
Edit settings.py:
1. Open mysite/settings.py for editing.
2. Set the value of STATIC_URL to the following URL. Replace <your-gcs-bucket> with the bucket name you created earlier.
```
https://storage.googleapis.com/<your-gcs-bucket>/static/
```
3. Close and save settings.py.
Edit app.yaml:
1. Open app.yaml for editing.
2. Run the following command from the command line:
```
gcloud sql instances describe [YOUR_INSTANCE_NAME]
```
3. From the output, copy the connectionName value for use in the next step.
4. Replace <your-cloudsql-connection-string> with connectionName from the previous step.
5. Close and save app.yaml.
Deploy the sample:
```
gcloud app deploy
```
Wait for the message that notifies you that the update has completed.

Seeing the app run in Google Cloud

The following command deploys the app as described in app.yaml and sets the newly deployed version as the default version, causing it to serve all new traffic.

In your browser, enter the following URL:

https://PROJECT_ID.REGION_ID.r.appspot.com

Replace the following:
- PROJECT_ID: Your Google Cloud project ID
- REGION_ID: A code that App Engine assigns to your app

Your request is served by a web server running in the App Engine flexible environment.

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 deploy the updated version by entering the same command that you used to deploy the app. The deployment creates a new version of your app and promotes it to the default version. The earlier versions of your app remain, as do their associated virtual machine (VM) instances. All of these app versions and VM instances are billable resources. To reduce costs, delete the non-default versions of your app.

For information about deleting the non-default versions of your app or stopping your VM instances, see Cleaning up.

Production

When you are ready to serve your content in production, in mysite/settings.py, change the DEBUG variable to False.

Understanding the code

The Django sample app was created by using standard Django tooling.

The following commands create the project and the polls app:

django-admin startproject mysite

python manage.py startapp polls

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

appengine/flexible/django_cloudsql/mysite/settings.py

View on GitHub

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>',
        # For MySQL, set 'PORT': '3306' instead of the following. Any Cloud
        # SQL Proxy instances running locally must also be set to tcp:3306.
        'PORT': '5432',
    }
}
# 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'

To specify how the app serves static content, in the settings.py file, set the value of STATIC_URL:

appengine/flexible/django_cloudsql/mysite/settings.py

View on GitHub

# 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:

appengine/flexible/django_cloudsql/app.yaml

View on GitHub

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

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

runtime_config:
  python_version: 3

Running Django in the App Engine flexible environment

Before you begin

Log in to gcloud

Downloading and running the app

Cloning the Django app

Linux/macOS

Windows

Setting up your local environment

Installing the Cloud SQL Proxy

Linux 64-bit

Linux 32-bit

macOS 64-bit

macOS 32-bit

Windows 64-bit

Windows 32-bit

Cloud SQL Proxy Docker image

Other OS

Creating a Cloud SQL instance

Initializing your Cloud SQL instance

Linux/macOS

Windows

Cloud Console

Postgres client

Configuring the database settings

Running the app on your local computer

Linux/macOS

Windows

Using the Django admin console

Deploying the app to the App Engine flexible environment

Seeing the app run in Google Cloud

Production

Understanding the code