Running Django on the App Engine standard environment
Django apps that run onApp Engine standard scale dynamically according to traffic.
This tutorial assumes that you're familiar with Django web development. Ifyou're new to Django development, it's a good idea to work throughwriting your first Django app before continuing.
While this tutorial demonstrates Django specifically, you can use this deployment processwith other Django-based frameworks, such asWagtail andDjango CMS.
This tutorial uses Django 4,which requires at least Python 3.8. App Engine standard supportsPython 3.7 and higher, including Python 3.8.
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 standard.
Costs
In this document, you use the following billable components of Google Cloud:
To generate a cost estimate based on your projected usage, use thepricing 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 role (
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 thegcloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Toinitialize the gcloud CLI, run the following command:
gcloudinit
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 role (
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 thegcloud CLI.
If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.
Toinitialize the gcloud CLI, run the following command:
gcloudinit
- If you haven't already done so, initialize App Engine and select your preferred region:
gcloudappcreate
Prepare your environment
Clone a sample app
The code for the Django sample app is in theGoogleCloudPlatform/python-docs-samples repository on GitHub.
You can eitherdownload the sample as a ZIP file and extract it or clone the repository to your local machine:
gitclonehttps://github.com/GoogleCloudPlatform/python-docs-samples.gitGo to the directory that contains the sample code:
Linux/macOS
cdpython-docs-samples/appengine/standard_python3/djangoWindows
cdpython-docs-samples\appengine\standard_python3\django
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 thePython development environment guide.
Confirm your Python is at least version 3.8.
python-VYou should see
Note: If you see a version number starting with "2", you may need to runPython 3.8.0or higher.python3instead ofpython. If so, remember to reference your chosen Python installation when runningpythoncommands.Create a Python virtual environment and install dependencies:
Linux/macOS
python-mvenvvenvsourcevenv/bin/activatepipinstall--upgradepippipinstall-rrequirements.txtWindows
python-mvenvvenvvenv\scripts\activatepipinstall--upgradepippipinstall-rrequirements.txt
Download Cloud SQL Auth Proxy to connect to Cloud SQL from your local machine
Note: If you are completing this tutorial from Cloud Shell, this section is not required.When deployed, your app uses the Cloud SQL Auth Proxy that is built intothe App Engine standard environment to communicate with your Cloud SQLinstance. However, to test your app locally, you must install and use a localcopy of the proxy in your development environment. For more details, refer to theCloud 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 thegcloud CLI.
Authenticate and acquire credentials for the API:
gcloudauthapplication-defaultloginDownload and install the Cloud SQL Auth Proxy to your local machine.
Linux 64-bit
- Download the Cloud SQL Auth Proxy:
curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.0/cloud-sql-proxy.linux.amd64
- Make the Cloud SQL Auth Proxy executable:
chmod+xcloud-sql-proxy
Linux 32-bit
- Download the Cloud SQL Auth Proxy:
curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.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+xcloud-sql-proxy
macOS 64-bit
- Download the Cloud SQL Auth Proxy:
curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.0/cloud-sql-proxy.darwin.amd64
- Make the Cloud SQL Auth Proxy executable:
chmod+xcloud-sql-proxy
Mac M1
- Download the Cloud SQL Auth Proxy:
curl-ocloud-sql-proxyhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.0/cloud-sql-proxy.darwin.arm64
- Make the Cloud SQL Auth Proxy executable:
chmod+xcloud-sql-proxy
Windows 64-bit
Right-clickhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.0/cloud-sql-proxy.x64.exe and selectSave Link As to download the Cloud SQL Auth Proxy. Rename the file tocloud-sql-proxy.exe.Windows 32-bit
Right-clickhttps://storage.googleapis.com/cloud-sql-connectors/cloud-sql-proxy/v2.20.0/cloud-sql-proxy.x86.exe and selectSave Link As to 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, whichcontains no shell. If you need a shell or related tools, then download an image based onalpineorbuster.For more information, seeCloud 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.20.0
Note: The Cloud SQL Auth Proxy uses a repository that supports the
gcr.iodomain but serves images from Artifact Registry. For more information, seeTransition from Container Registry.Other OS
For other operating systems not included here, you cancompile 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 thedatabase, media storage, and secret storage that support the deployed Djangoproject. These services are deployed in a specific region. For efficiency betweenservices, all services should be deployed in the same region.For more information about the closest region to you, seeProducts available by region.
This tutorial uses the integrated static asset hosting mechanisms in App Engine standard.Set up a Cloud SQL for PostgreSQL instance
Django officially supports multiple relational databases, but offers the mostsupport for PostgreSQL. PostgreSQL is supported by Cloud SQL, so thistutorial 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 theCloud SQL Instances page.
ClickCreate Instance.
ClickChoose PostgreSQL.
ForSQL Edition, choose "Enterprise".
ForEdition Preset, choose "Sandbox".
In theInstance ID field, enter
INSTANCE_NAME.Enter a password for the postgres user.
Keep the default values for the other fields.
ClickCreate Instance.
It takes a few minutes for the instance to be ready for use.
gcloud
Create the PostgreSQL instance:
gcloudsqlinstancescreateINSTANCE_NAME \--projectPROJECT_ID \--database-versionPOSTGRES_16 \--tierdb-n1-standard-2 \--regionREGION
Replace the following:
INSTANCE_NAME: the Cloud SQL instance namePROJECT_ID: the Google Cloud project IDREGION: theGoogle 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 theDatabases tab.
- ClickCreate database.
- In theDatabase Name dialog, enter
DATABASE_NAME. - ClickCreate.
gcloud
Create the database within the recently created instance:
gcloudsqldatabasescreateDATABASE_NAME \--instanceINSTANCE_NAMEReplace
DATABASE_NAMEwith a name for the database inside the instance.
Create a database user:
Note: Users created this way get additional database rights. SeeLimit the database user privileges for an alternative method.Console
- Within your instance page, go to theUsers tab.
- ClickAdd User Account.
- In theChoose how to authenticate dialog under "Built-in Authentication":
- Enter the username
DATABASE_USERNAME. - Enter the password
DATABASE_PASSWORD - ClickAdd.
gcloud
Create the user within the recently created instance:
gcloudsqluserscreateDATABASE_USERNAME \--instanceINSTANCE_NAME \--passwordDATABASE_PASSWORDReplace
PASSWORDwith a secure password.
Store secret values in Secret Manager
Now that the backing services are configured, Django needsinformation about these services. Instead of putting these values directly into the Django source code,this tutorial uses Secret Manager to store this informationsecurely.
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 secretvalue, and thedjango-environ package to load the values into the Django environment. The secret is configuredto be accessible by App Engine standard.
Create a file called
.env, defining the database connection string, the media bucket name, and a newSECRET_KEYvalue:echoDATABASE_URL=postgres://DATABASE_USERNAME:DATABASE_PASSWORD@//cloudsql/PROJECT_ID:REGION:INSTANCE_NAME/DATABASE_NAME >.envechoGS_BUCKET_NAME=PROJECT_ID_MEDIA_BUCKET >>.envechoSECRET_KEY=$(cat/dev/urandom|LC_ALL=Ctr-dc'[:alpha:]'|fold-w50|head-n1) >>.envStore the secret in Secret Manager:
Console
In the Google Cloud console, go to theSecret Manager page.
ClickCreate secret
In theName field, enter
django_settings.In theSecret value dialog, paste the contents of your
.envfile.ClickCreate secret.
Delete the local file to preventlocal setting overrides.
gcloud
Create a new secret,
django_settings, with the value of the.envfile:gcloudsecretscreatedjango_settings--data-file.envDelete the local file to preventlocal setting overrides:
rm.env
Configure access to the secret:
Console
Click thePermissions tab.
ClickGrant access.
In theNew Members field, enter
PROJECT_ID@appspot.gserviceaccount.com, and then pressEnter.In theRole drop-down menu, selectSecret Manager Secret Accessor.
ClickSave.
gcloud
Grant access to the secret to the App Engine standard service account:
gcloudsecretsadd-iam-policy-bindingdjango_settings\--memberserviceAccount:PROJECT_ID@appspot.gserviceaccount.com\--roleroles/secretmanager.secretAccessor
In the output, confirm that
bindingslists the new service account.
Run the app on your local computer
With the backing services configured, you can now run the app on your computer. This setup allows for local development, creating a superuser, and applying database migrations.
In a separate terminal, start the Cloud SQL Auth Proxy:
Linux/macOS
./cloud-sql-proxyPROJECT_ID:REGION:INSTANCE_NAMEWindows
cloud-sql-proxy.exePROJECT_ID:REGION:INSTANCE_NAMEThis step establishes a connection from your local computer to yourCloud SQL instance for local testing purposes. Keep theCloud SQL Auth Proxy running the entire time you test your app locally. Runningthis process in a separate terminal allows you to keep working whilethis process runs.
In the original terminal, set the Project ID locally (used by the Secret Manager API):
Linux/macOS
exportGOOGLE_CLOUD_PROJECT=PROJECT_IDWindows
setGOOGLE_CLOUD_PROJECT=PROJECT_IDSet an environment variable to indicate you are using Cloud SQL Auth Proxy (this value isrecognised in the code):
Linux/macOS
exportUSE_CLOUD_SQL_AUTH_PROXY=trueWindows
setUSE_CLOUD_SQL_AUTH_PROXY=trueRun the Django migrations to set up your models and assets:
pythonmanage.pymakemigrationspythonmanage.pymakemigrationspollspythonmanage.pymigratepythonmanage.pycollectstaticStart the Django web server:
pythonmanage.pyrunserver8080In your browser, go tohttp://localhost:8080.
If you are in Cloud Shell, click theWeb Preview button, and selectPreview on port 8080.
The page displays the following text: "Hello, world. You'reat the polls index." The Django web server running on your computer deliversthe sample app pages.
Press
Ctrl/Cmd+Cto stop the local web server.
Use the Django admin console
In order to log into Django's admin console, you need to create asuperuser. Since you have a locally accessible connection to the database, you can run management commands:
Create a superuser. You will be prompted to enter a username, email, and password.
pythonmanage.pycreatesuperuserStart a local web server:
pythonmanage.pyrunserverIn your browser, go tohttp://localhost:8000/admin.
Log in to the admin site using the username and password you used whenyou ran
createsuperuser.
Deploy the app to the App Engine standard environment
With all the backing services set up and the application tested locally, you can now deploy the app to App Engine standard:
- Upload the app by running the following command, which deploys the app as described in
app.yamland sets the newly deployed version as the default version, causing it to serve all new traffic:gcloud app deploy - Confirm the settings by typing "yes" when prompted.
- Wait for the message that notifies you that the update has completed.
- Open
app.yamland update the value ofAPPENGINE_URLwith your deployed URL:...env_variables: APPENGINE_URL: https://PROJECT_ID.uc.r.appspot.com - Upload your configuration changes:
gcloud app deploy
Running the deployed app
The app has been deployed, and now can be accessed:
Open the deployed website:
gcloudappbrowseAlternatively, display the URL and open manually:
gcloudappdescribe--format"value(defaultHostname)"
Your request is served by a web server running in the App Engine standard environment.
Updating the application
To update your application, make changes to the code, then run thegcloud app deploy command again.
The deployment creates anew version of your app and promotes it to the default version.The earlier versions of yourapp remain. All of these app versions are billable resources. To reduce costs,delete the non-default versions of your app.
Configuring for production
You now have a working Django deployment, but there are further steps you can take to ensure that your application is production-ready.
Disable debugging
Confirm that theDEBUG variable inmysite/settings.py is set toFalse. Thiswill prevent detailed error pages from being displayed to the user, which canleak information about the configurations.
Limit the database user privileges
Any users that are created by using Cloud SQL have the privileges associated with thecloudsqlsuperuser role:CREATEROLE,CREATEDB, andLOGIN.
To prevent the Django database user from having these permissions, manually create the user in PostgreSQL. You will need to have thepsql interactive terminal installed, or use Cloud Shell which has this tool pre-installed.
Console
In the Google Cloud console, activate Cloud Shell.
In Cloud Shell, use the built-in terminal to connect to your
INSTANCE_NAMEinstance:gcloudsqlconnectINSTANCE_NAME--userpostgresEnter the postgres user password.
You are now using
psql. You should see thepostgres=>prompt.Create a user:
CREATEUSERDATABASE_USERNAMEWITHPASSWORD'DATABASE_PASSWORD';Replace
PASSWORDwith a random, unique password.Grant full rights on the new database to the new user:
GRANTALLPRIVILEGESONDATABASEDATABASE_NAMETODATABASE_USERNAME;Exit
psql:\q
gcloud
Note: Any users that are created by using Cloud SQL have the privileges associated with thecloudsqlsuperuser role:CREATEROLE,CREATEDB, andLOGIN. This tutorial creates the user directlyin PostgreSQL.Start a connection to the SQL instance:
gcloudsqlconnectINSTANCE_NAME--userpostgresReplace
INSTANCE_NAMEwith the created Cloud SQL instance.Enter the postgres user password.
You are now using
psql. You should see thepostgres=>prompt.Create a user:
CREATEUSERDATABASE_USERNAMEWITHPASSWORD'DATABASE_PASSWORD';Grant full rights on the new database to the new user:
GRANTALLPRIVILEGESONDATABASEDATABASE_NAMETODATABASE_USERNAME;Exit
psql:\q
Understand the code
Sample application
The Django sample app was created using standard Django tooling. The following commands create the project and the polls app:
django-adminstartprojectmysitepythonmanage.pystartapppollsThe base views, models, and route configurations were copied fromWriting your first Django app (Part 1 andPart 2).
Secrets from Secret Manager
Thesettings.py file contains code that uses the Secret Manager Python API to retrieve the latest version of the named secret, and pull it into the environment (usingdjango-environ):
env=environ.Env(DEBUG=(bool,False))env_file=os.path.join(BASE_DIR,".env")ifos.path.isfile(env_file):# Use a local secret file, if providedenv.read_env(env_file)# ...elifos.environ.get("GOOGLE_CLOUD_PROJECT",None):# Pull secrets from Secret Managerproject_id=os.environ.get("GOOGLE_CLOUD_PROJECT")client=secretmanager.SecretManagerServiceClient()settings_name=os.environ.get("SETTINGS_NAME","django_settings")name=f"projects/{project_id}/secrets/{settings_name}/versions/latest"payload=client.access_secret_version(name=name).payload.data.decode("UTF-8")env.read_env(io.StringIO(payload))else:raiseException("No local .env or GOOGLE_CLOUD_PROJECT detected. No secrets found.")The secret is used to store multiple secret values to reduce the number of different secrets that needed to be configured.
CSRF configurations
Django has built-in protection againstCross Site Request Forgery (CSRF).Starting in Django 4.0, changes to the way this works mean that it's important to tell Djangowhat it's hosted URL is, so it can offer the best protections for users submitting data.
You supply the app's URL as an environment variable in thesettings.py fileThis is the value that Django uses for the relevant settings.
# SECURITY WARNING: It's recommended that you use this when# running in production. The URL will be known once you first deploy# to App Engine. This code takes the URL and converts it to both these settings formats.APPENGINE_URL=env("APPENGINE_URL",default=None)ifAPPENGINE_URL:# Ensure a scheme is present in the URL before it's processed.ifnoturlparse(APPENGINE_URL).scheme:APPENGINE_URL=f"https://{APPENGINE_URL}"ALLOWED_HOSTS=[urlparse(APPENGINE_URL).netloc]CSRF_TRUSTED_ORIGINS=[APPENGINE_URL]SECURE_SSL_REDIRECT=Trueelse:ALLOWED_HOSTS=["*"]Local secret overrides
If a.env file is found on the local filesystem, it is used instead of the value from Secret Manager. Creating a.env file locally can help with local testing (e.g. local development against a SQLite database, or other local settings).
Database connection
Thesettings.py file contains the configuration for your SQL database. It uses theenv.db() helperfromdjango-environ to load the connection string set inDATABASE_URL into theDATABASES setting.
When running the application locally and using the Cloud SQL Auth Proxy to access thehosted database, theUSE_CLOUD_SQL_AUTH_PROXY flag adjusts the databasesettings to use the proxy.
# Use django-environ to parse the connection stringDATABASES={"default":env.db()}# If the flag as been set, configure to use proxyifos.getenv("USE_CLOUD_SQL_AUTH_PROXY",None):DATABASES["default"]["HOST"]="127.0.0.1"DATABASES["default"]["PORT"]=5432Hosted static content
Theapp.yaml file contains configuration information for deployment to App Engine.Thisapp.yaml file specifies that App Engine serves static filesfrom thestatic/ directory:
runtime:python313env_variables:# This setting is used in settings.py to configure your ALLOWED_HOSTS# APPENGINE_URL: PROJECT_ID.uc.r.appspot.comhandlers:# This configures Google App Engine to serve the files in the app's static# directory.-url:/staticstatic_dir:static/# This handler routes all requests not caught above to your main app. It is# required when static routes are defined, but can be omitted (along with# the entire handlers section) when there are no static files defined.-url:/.*script:autoWhen running the app locally withDEBUG enabled, these files are served locally by Django:
fromdjango.confimportsettingsfromdjango.conf.urls.staticimportstaticfromdjango.contribimportadminfromdjango.urlsimportinclude,pathurlpatterns=[path("",include("polls.urls")),path("admin/",admin.site.urls),]+static(settings.STATIC_URL,document_root=settings.STATIC_ROOT)Clean up
To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, either delete the project that contains the resources, or keep the project and delete the individual resources.
Delete the project
What's next
- Learn how toconfigure PostgreSQL for production
- Learn more aboutDjango on Google Cloud
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-15 UTC.