Django apps that run on App Engine flexible scale dynamically according to traffic.
This tutorial assumes that 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.
While this tutorial demonstrates Django specifically, you can use this deployment process with other Django-based frameworks, such as Wagtail and Django CMS .
This tutorial uses Django 3, which requires at least Python 3.7 . App Engine flexible supports Python 3.7 .
Objectives
In this tutorial, you will:
- Create and connect a Cloud SQL database.
- Create and use Secret Manager secret values.
-
Deploy a Django app to App Engine flexible.
-
Host static files on Cloud Storage.
Costs
In this document, you use the following billable components of Google Cloud:
To generate a cost estimate based on your projected usage, use the pricing calculator .
Before you begin
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project : Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project
: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles .
-
Verify that billing is enabled for your Google Cloud project .
-
Enable the Cloud SQL Admin API, Secret Manager, and Cloud Build APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles . -
Install the gcloud CLI .
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project : Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
- Create a project
: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles .
-
Verify that billing is enabled for your Google Cloud project .
-
Enable the Cloud SQL Admin API, Secret Manager, and Cloud Build APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles . -
Install the gcloud CLI .
-
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity .
-
To initialize the gcloud CLI, run the following command:
gcloud init
- If you haven't already done so, initialise App Engine and select your preferred region:
gcloud app create
Prepare your environment
Clone a sample 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 / flexible_python37_and_earlier / django_cloudsqlWindows
cd python - docs - samples \ appengine \ flexible_python37_and_earlier \ django_cloudsql
Confirm your Python setup
This tutorial relies on Python to run the sample application on your machine. The sample code also requires installing dependencies
For more details, refer to the Python development environment guide .
-
Confirm your Python is at least version 3.7.
python - VYou should see
Python 3.7.0or higher. -
Create a Python virtual environment and install dependencies:
Linux/macOS
python - m venv venv source venv / bin / activate pip install -- upgrade pip pip install - r requirements . txtWindows
python - m venv venv venv \ scripts \ activate pip install -- upgrade pip pip install - r requirements . txt
Download Cloud SQL Auth Proxy to connect to Cloud SQL from your local machine
When deployed, your app uses the Cloud SQL Auth Proxy that is built into the App Engine flexible 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. For more details, refer to the Cloud SQL Auth Proxy guide .
The Cloud SQL Auth Proxy uses the Cloud SQL API to interact with your SQL instance. To do this, it requires application authentication through the gcloud CLI .
-
Authenticate and acquire credentials for the API:
gcloud auth application - default login -
Download and install the Cloud SQL Auth Proxy to your local machine.
Linux 64-bit
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.19.0/cloud-sql-proxy.linux.amd64
- Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
Linux 32-bit
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.19.0/cloud-sql-proxy.linux.386
- If the
curlcommand is not found, runsudo apt install curland repeat the download command. - Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
macOS 64-bit
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.19.0/cloud-sql-proxy.darwin.amd64
- Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
Mac M1
- Download the Cloud SQL Auth Proxy:
curl -o cloud-sql-proxy https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.19.0/cloud-sql-proxy.darwin.arm64
- Make the Cloud SQL Auth Proxy executable:
chmod +x cloud-sql-proxy
Windows 64-bit
Right-click https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.19.0/cloud-sql-proxy.x64.exe and select Save Link Asto download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe.Windows 32-bit
Right-click https://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.19.0/cloud-sql-proxy.x86.exe and select Save Link Asto download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe.Cloud SQL Auth Proxy Docker image
The Cloud SQL Auth Proxy has different container images, such as
distroless,alpine, andbuster. The default Cloud SQL Auth Proxy container image usesdistroless, which contains no shell. If you need a shell or related tools, then download an image based onalpineorbuster. For more information, see Cloud SQL Auth Proxy Container Images .You can pull the latest image to your local machine using Docker by using the following command:
docker pull gcr.io/cloud-sql-connectors/cloud-sql-proxy:2.19.0
Other OS
For other operating systems not included here, you can compile the Cloud SQL Auth Proxy from source .You can choose to move the download to somewhere common, such as a location on your
PATH, or your home directory. If you choose to do this, when you start the Cloud SQL Auth Proxy later on in the tutorial, remember to reference your chosen location when usingcloud-sql-proxycommands. - Download the Cloud SQL Auth Proxy:
Create backing services
This tutorial uses several Google Cloud services to provide the database, media storage, and secret storage that support the deployed Django project. These services are deployed in a specific region. For efficiency between services, all services should be deployed in the same region. For more information about the closest region to you, see Products available by region .
Set up a Cloud SQL for PostgreSQL instance
Django officially supports multiple relational databases, but offers the most support for PostgreSQL. PostgreSQL is supported by Cloud SQL, so this tutorial chooses to use that type of database.
The following section describes the creation of a PostgreSQL instance, database, and database user for the app.
-
Create the PostgreSQL instance:
Console
-
In the Google Cloud console, go to the Cloud SQL Instancespage.
-
Click Create Instance.
-
Click Choose PostgreSQL.
-
For SQL Edition, choose "Enterprise".
-
For Edition Preset, choose "Sandbox".
-
In the Instance IDfield, enter
INSTANCE_NAME. -
Enter a password for the postgres user.
-
Keep the default values for the other fields.
-
Click Create Instance.
It takes a few minutes for the instance to be ready for use.
gcloud
-
Create the PostgreSQL instance:
gcloud sql instances create INSTANCE_NAME \ -- project PROJECT_ID \ -- database - version POSTGRES_16 \ -- tier db - n1 - standard - 2 \ -- region REGION
Replace the following:
-
INSTANCE_NAME: the Cloud SQL instance name -
PROJECT_ID: the Google Cloud project ID -
REGION: the Google Cloud region
It takes a few minutes to create the instance and for it to be ready for use.
-
-
Within the created instance, create a database:
Console
- Within your instance page, go to the Databasestab.
- Click Create database.
- In the Database Namedialog, enter
DATABASE_NAME. - Click Create.
gcloud
-
Create the database within the recently created instance:
gcloud sql databases create DATABASE_NAME \ -- instance INSTANCE_NAMEReplace
DATABASE_NAMEwith a name for the database inside the instance.
-
Create a database user:
Console
- Within your instance page, go to the Userstab.
- Click Add User Account.
- In the Choose how to authenticatedialog under "Built-in Authentication":
- Enter the username
DATABASE_USERNAME. - Enter the password
DATABASE_PASSWORD - Click Add.
gcloud
-
Create the user within the recently created instance:
gcloud sql users create DATABASE_USERNAME \ -- instance INSTANCE_NAME \ -- password DATABASE_PASSWORDReplace
PASSWORDwith a secure password.
Set up a Cloud Storage bucket
You can store Django's included static assets, as well as user-uploaded media,
in highly-available object storage using Cloud Storage.
The django-storages[google]
package handles
Django's interaction with this storage backend.
Console
-
In the Google Cloud console, go to the Cloud Storagepage.
-
Click Create Bucket.
-
Enter the following (clicking "Continue" where needed):
- For Name, enter " PROJECT_ID _ MEDIA_BUCKET ".
- For Region, select REGION .
- For Storage Class, keep the defaults.
- For Prevent public access, clear "Enforce public access prevention".
- For Access Control, select "Fine-grained".
-
Keep the default values for the other fields.
-
Click Create.
gcloud
-
Create a Cloud Storage bucket:
gcloud storage buckets create gs : // PROJECT_ID _ MEDIA_BUCKET -- location = REGIONReplace
MEDIA_BUCKETwith a suffix for the media bucket. Combined with the project ID, this creates a unique bucket name.
Store secret values in Secret Manager
Now that the backing services are configured, Django needs information about these services. Instead of putting these values directly into the Django source code, this tutorial uses Secret Manager to store this information securely.
Create Django environment file as a Secret Manager secret
You store the settings required to start Django in a secured env file.
The sample app uses the Secret Manager API to retrieve the secret
value, and the django-environ
package to load the values into the Django environment. The secret is configured
to be accessible by App Engine flexible.
-
Create a file called
.env, defining the database connection string, the media bucket name, and a newSECRET_KEYvalue:echo DATABASE_URL = postgres:// DATABASE_USERNAME : DATABASE_PASSWORD @//cloudsql/ PROJECT_ID :REGION: INSTANCE_NAME / DATABASE_NAME > .env echo GS_BUCKET_NAME = PROJECT_ID _ MEDIA_BUCKET >> .env echo SECRET_KEY = $( cat /dev/urandom | LC_ALL = C tr -dc '[:alpha:]' | fold -w 50 | head -n1 ) >> .env -
Store the secret in Secret Manager:
Console
-
In the Google Cloud console, go to the Secret Manager page.
-
Click Create secret
-
In the Namefield, enter
django_settings. -
In the Secret valuedialog, paste the contents of your
.envfile. -
Click Create secret.
-
Delete the local file to prevent local setting overrides .
gcloud
-
Create a new secret,
django_settings, with the value of the.envfile:gcloud secrets create django_settings --data-file .env -
Delete the local file to prevent local setting overrides :
rm .env
-
-
Configure access to the secret:
Console
-
Click the Permissionstab.
-
Click Grant access.
-
In the New Membersfield, enter
PROJECT_ID @appspot.gserviceaccount.com, and then pressEnter. -
In the Roledrop-down menu, select Secret Manager Secret Accessor.
-
Click Save.

