Django

• Naked Django
• Use a sqlite database
• Activate the administration site
• Static files and admin media
• Use a postgresql database
• Create a staging deployment
• Convert an existing Django project
• Troubleshooting
• Advanced debugging with werkzeug
• External resources

Warning

For the impatients our there…

TL,DR? Wait, there are two things that you must know before trying to deploy your Django app on DotCloud:

1. The wsgi.py file should be at the root of your application.
2. Your Django project shouldn’t be at the root of your application, but in a subdirectory with a Python module name. So your manage.py file shouldn’t be in the same directory as wsgi.py, but in a subdirectory, with a name such as you can import it.

Naked Django

Let’s start with a minimal Django project.

First, on your local computer, create a directory to hold our DotCloud service and the Django project inside. Some of us love pasta, others love japanese food, so we will try to make both of them happy, and create a ramen project:

$ mkdir ramen-on-dotcloud
$ cd ramen-on-dotcloud
ramen-on-dotcloud$ django-admin startproject ramen

In the ramen-on-dotcloud directory, create a wsgi.py with the following content:

import os
import sys
os.environ['DJANGO_SETTINGS_MODULE'] = 'ramen.settings'
import django.core.handlers.wsgi
djangoapplication = django.core.handlers.wsgi.WSGIHandler()
def application(environ, start_response):
    if 'SCRIPT_NAME' in environ:
        del environ['SCRIPT_NAME']
    return djangoapplication(environ, start_response)

Specify the Python packages required by our project. This is done with a pip-like file, conveniently named requirements.txt, located in our project:

ramen-on-dotcloud$ echo django >requirements.txt

The complete specs of the requirements file are detailed at http://www.pip-installer.org/en/latest/requirement-format.html

As seen in firststeps, before pushing our code, we first need to deploy a Python service:

ramen-on-dotcloud$ dotcloud deploy -t python ramen.www

We can now push the code:

ramen-on-dotcloud$ dotcloud push ramen.www .
# rsync . code
sending incremental file list
./
[...rsync transfers our stuff...]
[...at some point, pip will kick in to install our dependencies...]
# [  -e "code/./requirements.txt" ] && pip install --download-cache=~/.pip-cache -r code/./requirements.txt
Downloading/unpacking django (from -r code/./requirements.txt (line 1))
[...and at the end, supervisord gets restarted...]
Starting supervisor: supervisord.

Point your browser to http://www.ramen.dotcloud.com/: you should see the “Welcome to Django” page.

Use a sqlite database

Let’s add a sqlite database and do a “syncdb”.

Edit the file ramen/settings.py and change the database engine to sqlite3, and specify a database name (required for sqlite operation). The beginning of the settings.py file will look like the following:

DATABASES = {
  'default': {
      'ENGINE': 'django.db.backends.sqlite3',
      'NAME': '/home/dotcloud/ramen.db',
      'USER': '',
      'PASSWORD': '',
      'HOST': '',
      'PORT': '',
  }
}

Since we have modified our code, we must push it again:

ramen-on-dotcloud$ dotcloud push ramen.www .

Now run the “syncdb” management command to initialize the sqlite database and create Django tables. This is achieved through the “dotcloud run” command:

ramen-on-dotcloud$ dotcloud run ramen.www python current/ramen/manage.py syncdb

Like a “regular” syncdb operation, this will ask you if you want to create a Django superuser. That’s the perfect timing to do it!

Your sqlite database and Django basic tables have been created. But we can’t do anything with it yet; so in the next paragraph, we will activate the Django administration site.

Activate the administration site

To show off our new shiny (local) database, we will activate the administration site.

Edit ramen/settings.py, and uncomment the following line (in the INSTALLED_APPS list) by removing the #:

# 'django.contrib.admin',

Edit ramen/urls.py; uncomment the two following lines:

# from django.contrib import admin
# admin.autodiscover()

And this one:

# (r'^admin/', include(admin.site.urls)),

Push your code (again!):

ramen-on-dotcloud$ dotcloud push ramen.www .

You can now go to http://www.ramen.dotcloud.com/admin/ (remember to replace the beginning of the URL with your actual service and deployment name), and sign on using the login and password that you specified when doing the initial syncdb.

But, wait! Instead of the nice theme of the Django administration site, we are getting dull, blank forms! That’s because we are missing the admin media (CSS and JS static files used by Django admin). We will see in the next paragraph how to fix that.

Static files and admin media

By default, the Python service will deliver the “static” subdirectory as static files. We must therefore do the following:

• create this static directory (since it does not exist yet in our Django project);
• copy (or symlink) Django admin media files into this static directory;
• instruct Django (through settings.py) of the path to use.

Django admin media files are shipped inside the Django distribution. On a Debian system, it is generally under /usr/share/pyshared/django/contrib/admin/media. On our DotCloud system, Django was installed inside a virtual environment, and the files should be somewhere around /home/dotcloud/env/lib/python2.6/site-packages/django/contrib/admin/media (phew!). Since this path could possibly change, we will use a dynamic method to compute the media path.

In the ramen-on-dotcloud directory, create a file named “postinstall”, with the following content:

#!/usr/bin/env python
import os
# To import anything under django.*, we must set this variable.
os.environ['DJANGO_SETTINGS_MODULE'] = 'ramen.settings'
# Import the admin module. The media directory is right under it!
import django.contrib.admin
# Retrieve the absolute path of the admin module.
admindir = os.path.dirname(django.contrib.admin.__file__)
# Add /media behind it.
mediadir = os.path.join(admindir, 'media')
# Compute the path of the symlink under the static directory.
staticlink = os.path.join('static', 'admin_media')
# If the link already exists, delete it.
if os.path.islink(staticlink):
    os.unlink(staticlink)
# Install the correct link.
os.symlink(mediadir, staticlink)

Then, make this script executable:

ramen-on-dotcloud$ chmod +x postinstall

This script will be automatically executed each time you do a “dotcloud push”. It will automatically re-create a symlink, /static/admin_media, pointing to the right admin media directory. This will continue to work even if this directory changes (because you install a newer version of Django, or because DotCloud Python service changes a few internal details).

Edit ramen/settings.py, find the ADMIN_MEDIA_PREFIX line, and update it as follows:

ADMIN_MEDIA_PREFIX = '/static/admin_media/'

Create the static directory (don’t forget this step or the postinstall script will fail):

ramen-on-dotcloud$ mkdir static

Last step is, of course, “dotcloud push ramen.www .” to upload your modified files and run the postinstall script.

Go back to the admin login page: the admin theme should now show up.

Use a postgresql database

As you know, sqlite is not the best choice for a production Django project. Therefore, we will see how to add a PostgreSQL service on DotCloud, and how to configure our Django project to use it.

Creating a PostgreSQL deployment is very simple:

$ dotcloud deploy -t postgresql ramen.sql

Retrieve the connection parameters of the newly created service:

$ dotcloud info ramen.sql
config:
    postgresql_password: bAJYyA/_;(
deployment: ramen
name: ramen.sql
ports:
-   name: ssh
    url: ssh://postgres@sql.ramen.dotcloud.com:1088
-   name: sql
    url: pgsql://root:bAJYyA/_;(@sql.ramen.dotcloud.com:1087
type: postgresql

Create the ramen database on the PostgreSQL service:

$ dotcloud run ramen.sql -- createdb -O root ramen

Update ramen/settings.py to use your new PostgreSQL database; you should edit the DATABASES section in the beginning of the file so it looks like the following:

DATABASES = {
  'default': {
      'ENGINE': 'django.db.backends.postgresql_psycopg2',
      'NAME': 'ramen',
      'USER': 'root',
      'PASSWORD': 'bAJYyA/_;(',
      'HOST': 'sql.ramen.dotcloud.com',
      'PORT': '1087',
  }
}

Push the new settings:

ramen-on-dotcloud$ dotcloud push ramen.www .

Since we changed the database backend, we should issue a syncdb again:

ramen-on-dotcloud$ dotcloud run ramen.www python current/ramen/manage.py syncdb

It will ask you again to create the Django superuser.

Create a staging deployment

If you are an experienced Django developer and a die-hard system administrator, you might be left unimpressed with this tutorial. After all, we had to create a custom wsgi.py script and a postinstall hook to make everything work properly. Don’t leave now! We have more for you.

Let’s setup a staging environment to test new code without touching production.

Create the new Python service:

ramen-on-dotcloud$ dotcloud deploy -t python ramen.staging

Push your code to the new Python service:

ramen-on-dotcloud$ dotcloud push ramen.staging .

Point your browser to http://staging.ramen.dotcloud.com/admin/; voilà, you’re done.

Nice, huh?

Convert an existing Django project

Let’s summarize the work needed to convert an existing Django project to run on DotCloud:

1. Specify your Python dependencies in a pip-style requirements.txt file.
2. Convert your Django project to a WSGI application (using a wsgi.py boilerplate file as seen above).
3. Move static files (media files and URLs) to /static.
4. Install the postinstall hook to handle admin media (this can be skipped if you do not use the adminsitration site at all).
5. If you want to run the database service on DotCloud, deploy it, retrieve its connection parameters and edit your settings.py accordingly.
6. Push your code to a python service.

Troubleshooting

If things don’t work as expected, check the logs! The easiest thing is to run “dotcloud logs ramen.www”, and then repeat the request which caused problems in the first place.

If you want to examine older logs, use “dotcloud ssh ramen.www”, and check the logs – the first one should be the nginx error log, in /var/log/nginx/ramen-www.error.log; and then the uwsgi log, in /var/log/supervisor/uwsgi.log.

Advanced debugging with werkzeug

If you already used the werkzeug debugger (or if you didn’t, but are looking for an awesome online debugger for your Django app), maybe you want to know how to get it running on DotCloud.

It usually involves installing django-extensions and then invoking “manage.py runserver_plus”. How do we do that on DotCloud?

Follow those simple steps:

1. Use the following wsgi.py file:

   import os
   import sys
   os.environ['DJANGO_SETTINGS_MODULE'] = 'ramen.settings'
   import django.core.handlers.wsgi
   djangoapplication = django.core.handlers.wsgi.WSGIHandler()
   def application(environ, start_response):
       if 'SCRIPT_NAME' in environ:
           del environ['SCRIPT_NAME']
       return djangoapplication(environ, start_response)
   # The following lines enable the werkzeug debugger
   import django.views.debug
   def null_technical_500_response(request, exc_type, exc_value, tb):
       raise exc_type, exc_value, tb
   django.views.debug.technical_500_response = null_technical_500_response
   from werkzeug.debug import DebuggedApplication
   application = DebuggedApplication(application, evalex=True)

2. Add “werkzeug” to your requirements.txt file.
3. And finally “dotcloud push” your app code.

The new wsgi.py file does two things:

1. Wrap the WSGI application with the werkzeug debugger. Any exception raised (and uncaught) by the WSGI application will trigger the werkzeug debugger.
2. Disable the standard exception-catching mechanism of Django – if we don’t do that, exceptions will be caught before they make it to the werkzeug debugger.

Now, exceptions will be shown not only with a traceback, but also an interactive JS-enabled console, allowing you to inspect the whole stack (including local variables and everything) with a Python prompt!

External resources

Would you like to know more?

• Deploying my Django application to DotCloud (Ken Cochrane)
• Quickstart for Django Piston API on Dotcloud (Brierwood Design)

If you wrote something interesting as well, don’t hesitate to ping us so we can add it there!