Python Django Skeleton for Google App Engine

A skeleton for building Python applications on Google App Engine with the Django Web Framework using Cloud SQL.

See our other Google Cloud Platform github repos for sample applications and scaffolding for other python frameworks and use cases.

Note that this project no longer uses the the SDK-provided Django 1.5 library but uses pip -t to vendor Django 1.9 into the lib/ folder.

This project is based on the introductory Django Tutorial polls applications.

Project Creation

The basic skeleton of this project was created using the standard Django commands:

• Use the standard Django command to start the project

django-admin startproject mysite

• Edit the DATABASE field in mysite/settings.py to use the CloudSQL instance locally, and use the Unix socket to talk to the same CloudSQL instance through a Unix socket when deployed
• Create appengine_config.py to ensure that libraries vendored into lib/ are on Python's sys.path when run.
• Create app.yaml and setup a static file handler in the same folder htat mysite/settings.py is configured to collect static files. All other routes are directed to Django's WSGI handler.

Enable Cloud SQL

This project assumes you are using CloudSQL as your database. CloudSQL is a managed MySQL instance hosted by Google Cloud, although you could also host a MySQL instance elsewhere and use that. Please see instructions below for how to enable create a CloudSQL instance.

For better scalability, consider Cloud Datastore, although you must use a custom backend such as Djangae for your models to work with it.

Run Locally

1. Install the App Engine Python SDK. See the README file for directions. You'll need python 2.7 and pip 7.0 or later installed too.

2. Clone this repo

   git clone https://github.com/GoogleCloudPlatform/appengine-django-skeleton.git
   

3. Install dependencies. There are two types of dependencies. requirements-local.txt contains libraries that are already expressed in app.yaml, like MySQL. Since app.yaml includes them in the runtime, they don't need to be installed to deploy the app, but they do need to be installed locally to run the app locally. You can use `pip install -r requirements-local.txt' to install them on your system or in a virtualenv, but the libraries should not be included in the project directory or uploaded to App Engine, where instead the bundled version is used.

   requirements-vendor.txt includes dependencies that should be 'vendored', which means its completely included in the directory at time of deployment. This can only be done for pure Python libraries that don't require system libraries. In this case, a recent version of Django is vendored. These vendored libaries can be added to the project using the pip -t flag, which installs it directly into the folder specified, in this case the lib folder. In order to make this project deployable directly after clone, the vendored libraries were already checked into this repo, but new ones can be added and then installed using the pip -t flag.

   # vendor Django directly into the project `lib` folder
   pip install -r requirements-vendor.txt -t lib
   # install globally or within a virtualenv for local testing
   pip install -r requirements-local.txt
   

4. Setup your Python path. Since Django is being added to the lib/ directory along with other vendored dependencies, the lib/ directory must be added to your Python import path in order for the libraries to be imported correctly outside of App Engine or dev_appserver, such as when you run the Django management console locally.

One way to accomplish this is to use the PYTHONPATH environment variable, which might look like this (assuming you are running from the repo's directory):

export PYTHONPATH=$(pwd)/lib

The pwd command fills in your current directory (appengine-django-skeleton), so that adds the absolute path of the lib directory to the Python import path.

Another approach would be to add it to the import path in manage.py like this:

sys.path.append('lib')

1. Create a new CloudSQL instance.

Please note that only 1st generation CloudSQL instance are currently supported for Google App Engine applications.

* From the Google Cloud Console, go to [Storage > CloudSQL> Create Instance](https://console.developers.google.com/project/_/sql/create)
* Under [Access Control > IP Address](https://console.developers.google.com/project/_/sql/instances/polls/access-control/ip),  Request IPv4 Address. This address will be your HOST for remote access to the
  CloudSQL instance in mysite/settings.py, so replace `<your-database-host>` with this address.
* Under [Databases](https://console.developers.google.com/project/_/sql/instances/polls/databases), click New Database and create the name for your database in mysite/settings.py. Replace
  `<your-database-name>` with this value.

At this point, your deployed AppEngine application can access the database, after you replace `<your-project-id>:<your-cloudsql-instance>` and
`<your-database-name>` in mysite/settings.py. The following instructions are to connect to the same CloudSQL instance
locally. Alternatively, you could install a local MySQL instance and use that in development.

* Under [Access Control > Authorization](https://console.developers.google.com/project/_/sql/instances/polls/access-control/authorization) Under "Allowed Networks", click "Add item", and add Network 0.0.0.0/0. This opens up
      access to your CloudSQL instance from any network. Stricter firewall settings should be considered for production
      applications.
* Under  [Access Control > Authorization](https://console.developers.google.com/project/_/sql/instances/polls/access-control/users), Click
      "Create user account". Create a username and password and edit mysite/settings.py DATABASES
      to reflect this. Replace `<your-database-user>` and `<your-database-password>` with these variables.

Note in myproject/settings.py, the deployed app does not use the IP or user created, but instead talks to the instance through a Unix socket as root. When testing locally, use the settings created above to access the database.

1. Create and run the Django migrations:

   python manage.py migrate
   

2. Run this project locally from the command line:

   dev_appserver.py app.yaml
   

You can also run the server using Django's server, assuming you install the dependencies:

python manage.py runserver

Visit the application http://localhost:8080

See the development server documentation for options when running dev_appserver.

Deploy

To deploy the application:

1. Use the Google Developer's Console to create a project, and note the project ID created. The project ID is sometimes the project name provided, and sometimes an auto-generated name.

2. Collect the static files into the static/ directory

   python manage.py collectstatic
   

3. Verify that <your-cloud-project-id> and <your-database-name> have been replaced in mysite/settings.py with your Cloud Project ID and your database name respectively.

4. Deploy the application with

   appcfg.py -A <your-project-id> update app.yaml
   

   or using the new gcloud SDK commands. If you want to use the gcloud command line tool, you'll have to remove the version flag from app.yaml, which is now specified in the command line. You can also use the --version flag when deploying with appcfg.py.

   gcloud init # only required once
   gcloud preview app deploy app.yaml --promote
   

5. Congratulations! Your application is now live at https://your-app-id.appspot.com

Installing Libraries

See the Third party libraries page for libraries that are already included in the SDK. To include SDK libraries, add them in your app.yaml file. Other than libraries included in the SDK, only pure python libraries may be added to an App Engine project.

Alternatively, pure Python libraries can be added to requirements.txt, and installed using pip -t into the lib/ folder and accessed directly through there.

Feedback

Star this repo if you found it useful. Use the github issue tracker to give feedback on this repo.

Contributing changes

See CONTRIBUTING.md

Licensing

See LICENSE