Monthly Archives: April 2012

Deploying Django 1.4 to Heroku

Note: It is assumed that your are keeping track of your changes using Git. If you aren’t, you’ll need to be to deploy to Heroku.

If there is one thing that scares beginners away from Django, its the idea of deployment. For a PHP programmer, deployment can be as simple as FTP’ing some files to a server, and boom, deployed. This isn’t to say that PHP deployment is simple. If you have to do it from scratch (get apache running, get your db installed, get PHP installed and configured, etc, etc) it can still be very complex, but many hosting companies take care of this for you. It’s almost like you never even have to think about it, which isn’t always the case for Django. That doesn’t mean its a bad thing, just…different.

So where do we start? Heroku is as good a place as any.

Heroku


Heroku is a cloud service for easy deployment of web applications. Initially it was Ruby only, but has been working hard to become a deployment service for many languages including Java, Python, and Node.js. Deploying to Heroku assumes a few things:

  1. You are familiar with Git and use it to track your code changes.
  2. You are at least passingly familiar with PostgreSQL, because that’s what you will being using. (You can use other storage devices, but PostgreSQL is the default and easiest to setup.
  3. You use PIP to manage your project’s requirements. If you aren’t doing this, you need to be. (seriously, it’s worth the effort)

Now that we have that out of the way, let’s get started. Before we can proceed further, you’ll need to get a Heroku account set up. For our testing purposes, a free account should be plenty.

  1. Go to Heroku.com and set up an account.
  2. Go to https://toolbelt.herokuapp.com and download the Herok toolbelt. Follow the directions on this page up to the “login” section.

That’s all for setting up Heroku for now. Next, we’re going to move on to configure Django so it can be deployed.

Django

Django gives you the flexibility to use almost any database under the sun. I generally develop using MySQL, but Heroku uses Postgres. As long as you haven’t been hand-tailoring queries, this shouldn’t provide any problem whatsoever. To make your project compatible with Heroku, you need to install the psycopg2 library.

pip install psycopg2

Now that you have the Postgres library installed, when your app is pushed to Heroku, Heroku will append some code to the end of your settings.py file that will point your install to the correct database.

Speaking of settings.py, you’ll also need to get your template and media paths set up correctly. To do that, add the following to the top of your settings.py and then set your paths to look like this:

import os.path
root = os.path.dirname(__file__).replace('\\','/')
 
MEDIA_ROOT = root + '/../media/'
STATIC_ROOT = root + '/../static/'
TEMPLATE_DIRS = (
    root +'/../templates',
)

We use this calculate root variable because it’s kind of a pain to know the path of your install on Heroku. This way it doesn’t matter where you deploy your app to, it should just work. Another thing to consider is static files. Heroku can be made to serve them, but having the same domain that is serving your site serve your static files is bad practice.

Wrapping it up

Now that Django is configured for Heroku deployment, all that’s left is to deploy it! The first thing we need to do is create a requirements file so that Heroku knows what packages to install. At the top level of your project, run the following:

pip freeze > requirements.txt

Great, now if you look at the generated file you can see what software Heroku is going to install for you. Next up, we’re going to create an app on Heroku (assuming you set up the Heroku tool belt correctly). In the top level directory of your project, run the following.

heroku create --stack cedar

This added your new Heroku app as a remote on your local Git repository. All you do to deploy is:

git push heroku master

Which should give you some output that looks like:

Counting objects: 10, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (10/10), 3.59 KiB, done.
Total 10 (delta 0), reused 0 (delta 0)

-----> Heroku receiving push
-----> Python/Django app detected
-----> Preparing Python interpreter (2.7.2)
-----> Creating Virtualenv version 1.7
       New python executable in .heroku/venv/bin/python2.7
       Also creating executable in .heroku/venv/bin/python
       Installing distribute........done.
       Installing pip...............done.
       Running virtualenv with interpreter /usr/local/bin/python2.7
-----> Activating virtualenv
-----> Installing dependencies using Pip version 1.0.2
       Downloading/unpacking Django==1.4 (from -r requirements.txt (line 1))
       ...
       Successfully installed Django psycopg2
       Cleaning up...
-----> Injecting Django settings...
       Injecting code into ./hellodjango/settings.py to read from DATABASE_URL
-----> Discovering process types
       Procfile declares types         -> (none)
       Default types for Python/Django -> web
-----> Compiled slug size is 9.3MB
-----> Launching... done, v4
       http://simple-spring-9999.herokuapp.com deployed to Heroku

To git@heroku.com:afternoon-sword-29.git
* [new branch]      master -> master

On the line immediately after “—–> Launching… done,…”, the url of your project is displayed. Before you go to it though, you need to run syncdb on Heroku. The Heroku toolbelt makes this pretty easy:

heroku run python manage.py syncdb

Conclusion

That’s all there is to it. If you get stuck, feel free to leave a comment. Heroku also has a great guide for getting up and running and explains some more features of the Heroku tool belt. That can be found here.

Up and Running with Django 1.4

As with any new web framework, getting started can seem daunting. Even though Django has some of best documentation of any framework, it can still be a pain to figure out how things work. The goal of this post is to help you, the Django newcomer, get up an running with a simple blog.

Step 1: Your Environment

One thing that isn’t clearly stated in most tutorials is that how you set up your environment can either make or break your Django experience. To make your Django experience as easy as possible, you’ll need to make sure that you have two packages installed: virtualenv and virtualenvwrapper
Virtualenv can be installed using pip, and virtualenvwrapper can be installed by following the instructions on it’s site. Once you have both of these installed, you’re going to create something called a virtual environment. A virtual environment allows you to install any packages you need for your Django development without having it interfere with the rest of your system. It also allows you to create a requirements file, which allows other people to replicate your environment. To get started, we use the mkvirtualenv command.

mkvirtualenv myblog

If you at some point close your terminal window and want to load your virtual environment again you can use the workon command.

workon myblog

If by chance you don’t want to work on this environment any more, you use the deactivate command.

deactivate

So bringing it all together, we’re going to create an environment, create a directory to play around in, and then install django.

cd ~/Desktop
mkvirtualenv myblog
mkdir blog
pip install django

Step 2: Create a Django Project

Now that we have our environment set up we need to create our first project. We’re going to call it “blog”.

cd blog
django-admin.py startproject blog .

If you look in the blog directory now, you’ll see two things: a folder named blog and a file named manage.py. The manage.py file is used to administer your project. Using it you’ll sync model changes, run the server, and collect static assets. So why don’t we try running the server?

chmod +x manage.py
./manage.py runserver

The first line allows the file to be executed, and the second line starts the server. Once the second line is executed you should see the following:

(myblog)jack@jack-HP-HDX-16-Notebook-PC:~/Desktop/blog$ chmod +x manage.py
(myblog)jack@jack-HP-HDX-16-Notebook-PC:~/Desktop/blog$ ./manage.py runserver
Validating models...

0 errors found
Django version 1.4, using settings 'blog.settings'
Development server is running at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Once your development server is running, any changes you make to your files will be noticed and served automatically. If you check out the address that the server is running at, you should see this:

Step 3: Configuring a database

If we’re going to create a blog, we need to be able to store information. To do that, and database is required. In the newly create blog folder, there is a file called settings.py. That file is where we configure our server and add any apps we create. First things first though, we need a database. The Django ORM does a great job of abstracting out the database layer for us, so we can plug in basically any database that we want. For the sake of simplicity, we’re going to use SQLite. To create a SQLite database, make sure that you have the SQLite3 package installed on your operating system. Make sure you are in the same folder as the settings.py file, and then execute the following commands:

sqlite3 blog.db
sqlite> .tables #Look ma, no tables in here!
sqlite> .q #quit

Now that you have a database configured, you can crack open the settings.py file and change this bit of code:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.',
        'NAME': '',
        'USER': '',
        'PASSWORD': '',
        'HOST': '',
        'PORT': '',
    }
}

to this:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': 'blog.db',
        'USER': '',
        'PASSWORD': '',
        'HOST': '',
        'PORT': '',
    }
}

Now that your Django project knows about your database, you need to have it create some tables for you. Go back to the directory with manage.py in it and run:

./manage.py syncdb

Once you run syncdb, you’ll get some output that looks like this:

./manage.py syncdb
Creating tables ...
Creating table auth_permission
Creating table auth_group_permissions
Creating table auth_group
Creating table auth_user_user_permissions
Creating table auth_user_groups
Creating table auth_user
Creating table django_content_type
Creating table django_session
Creating table django_site

You just installed Django's auth system, which means you don't have any superusers defined.
Would you like to create one now? (yes/no): yes
Username (leave blank to use 'jack'): 
E-mail address: jack.slingerland@gmail.com
Password: 
Password (again): 
Superuser created successfully.
Installing custom SQL ...
Installing indexes ...
Installed 0 object(s) from 0 fixture(s)

Step 4: The Posts App

A Django powered website consists of many smaller “apps”. For instance, a blog may have a posts app and a photo app. The idea is that things that aren’t concerned with each other (photos,posts) should be separate entities. For our blog projects we’re going to only use one app, and we’ll call it posts.
Creating an app is easy. As usual, Django does most of the work for you so you don’t get bogged down writing a bunch of tedious boilerplate code. Navigate back to the top of your Django project (the directory with manage.py in it) and do the following:

./manage.py startapp posts

If you check out your project now, you’ll see a new directory called posts. If you descend into that directory, you’ll see 4 files.

  • __init__.py: Let’s Python know that this directory is a package. This has more uses, but it’s beyond the scope of this post.
  • models.py: We define how our models (tables) should look and act.
  • views.py: This is where we grab data from out model, massage it to our needs, and then render it to a template.
  • tests.py: Unit tests go here.

Just because the app is created, doesn’t mean that Django recognizes it. You actually have to add the app to the INSTALLED_APPS section of the settings.py file. To do that, add a line to the end of the INSTALLED_APPS list.

'posts', # Don't forget the trailing comma!

Step 5: The Post Model

We’re finally to the part where we get to write code! But before we dive in, we need to think about what a blog post actually is. It will generally contain content, a title, and posted on date. With that in mind, open posts/models.py in your editor and add the following:

class Post(models.Model):
	title = models.CharField(max_length=100)
	content = models.TextField()
	post_date = models.DateTimeField(auto_now=True)

Once you’ve added those, save the file and then go back to manage.py and run syncdb. You should get some output that looks like:

./manage.py syncdb
Creating tables ...
Creating table posts_post
Installing custom SQL ...
Installing indexes ...
Installed 0 object(s) from 0 fixture(s)

If we hadn’t added the posts app to our settings.py file, the syncdb command wouldn’t have generated our table for us.

Step 5: The Admin

One of the best parts about Django is it’s free admin interface that you get. The admin isn’t enabled by, but it’s pretty easy to set up. First off, we need to open settings.py and uncomment two lines.

INSTALLED_APPS = (
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    # Uncomment the next line to enable the admin:
    'django.contrib.admin',
    # Uncomment the next line to enable admin documentation:
    'django.contrib.admindocs',
    'posts',
)

As the comments say, uncomment the lines that say “django.contrib.admin” and “django.contrib.admindocs”. The admindocs line isn’t necessary, but it’s nice for completeness. The second step is to set up the url configuration for the admin. Go to your urls.py file and make it look like this:

from django.conf.urls import patterns, include, url
 
from django.contrib import admin
admin.autodiscover()
 
urlpatterns = patterns('',
 
    url(r'^admin/doc/', include('django.contrib.admindocs.urls')),
    url(r'^admin/', include(admin.site.urls)),
)

Now that the admin is enabled, we need to add our model to it. In the blog app folder (same folder as models.py), create a file called admin.py and put the following in it:

from posts.models import Post
from django.contrib import admin
 
admin.site.register(Post)

All this does is let the admin know that it can manage your model for you. Since you technically added a new app (the admin app), you’ll need to run syncdb again.

./manage.py syncdb
Creating tables ...
Creating table django_admin_log
Installing custom SQL ...
Installing indexes ...
Installed 0 object(s) from 0 fixture(s)

Go ahead an start the server again, and go to the admin. It should be located at http://127.0.0.1:8000/admin/. You’ll be presented with a login screen, with which you’ll use the credentials you entered in the initial setup. Once you’re logged in, you’ll see this:

Now that you can see the Posts model in the admin, click the “add” button next to it. When you do, you’ll see a form like this.

Enter a title and some content, and then click “Save and Add Another”. Enter another title a and some content, and then click “Save”. You’ll be presented with a screen with two entries on it, that both say “Post object”.

Now, “Post object” doesn’t do a very good job of describing your post. What if you want to edit it? You won’t know what is in each post until you click into it. To fix that, go to models.py and modify your Post model to look like this:

class Post(models.Model):
	title = models.CharField(max_length=100)
	content = models.TextField()
	post_date = models.DateTimeField(auto_now=True)
 
	def __unicode__(self):
		return self.title

Now when you view your post list, you’ll see the post titles instead of “Post object”.

Step 6: URLconfs

We now have a few posts in the database and can edit them in the Django admin. The next step is to set up our url structure that will allow users to view the posts on the front end of the site. Open urls.py and add the lines to it that have the “#Added” comment at the end of them.

from django.conf.urls import patterns, include, url
 
from django.contrib import admin
admin.autodiscover()
 
from posts.views import * #added
 
urlpatterns = patterns('',
    ('^$', home), #added
    (r'^post/(?P<post_id>\d+)/$',post_specific), #added
    url(r'^admin/doc/', include('django.contrib.admindocs.urls')),
    url(r'^admin/', include(admin.site.urls)),
)

The first line added tells Python about your views (we’ll get to them next). The 2nd and 3rd lines added specify how certain urls are handled. The 2nd added line defines your home URLconf, and the 3rd added line defined your route for specific posts. Next, open yours posts/views.py file and add the following:

from django.shortcuts import render_to_response
from django.http import Http404
from posts.models import Post
 
def home(request):
	return render_to_response("home.html",{
		"posts" : Post.objects.all().order_by('post_date')
	})
 
def post_specific(request, post_id):
	try:
		p = Post.objects.get(pk=post_id)
	except:
		raise Http404
 
	return render_to_response("post_specific.html",{
		"post" : p
	})

In the first few lines we import some things we’ll need:

  • The ability to raise a 404 error.
  • Our Post model
  • A shortcut for rendering templates

The two functions we created are pretty straight forward. The home function takes all of the posts, and sends them to the “home.html” template where they will be rendered. The post_specific function checks to see if the post id that is passed in exists. If it does, it grabs that post and sends it on to the template. If it doesn’t, it raises a 404 error. Now, we need to make those templates.

Step 7: Templates

Creating templates is honestly the easiest part of the whole process. In your settings.py file, there is a variable called TEMPLATE_DIRS. You need to add the path to your templates folder in there. For instance, I created a folder called “templates” at the top level of my Django app, so mine looks like:

TEMPLATE_DIRS = (
    '/home/jack/Desktop/blog/templates',
)

Now in your templates directory, create home.html and post_specific.html. In home.html put the following:

<html>
	<head>
		<title>All posts!</title>
	</head>
	<body>
		<ol>
			{% for p in posts %}
			<li><a href='/post/{{ p.id }}'>{{ p.title }}</a></li>
			{% endfor %}
		</ol>
	</body>
</html>

and in post_specific.html put:

<html>
	<head>
		<title>{{ post.title }}</title>
	</head>
	<body>
		{{ post.content }}
		<p />
		<a href='/'>Back</a>
	</body>
</html>

Once everything is saved, go to http://127.0.0.1:8000 and check out your (simple) blog!

Next Steps

This is a very simplified tutorial. The goal is to help someone get started with something easy without getting bogged down in details. One of the greatest things about Django though is that the more details you learn, the greater it gets. With that in mind, I highly suggest checking out the following sites for more learning. Good luck!

  1. https://docs.djangoproject.com/en/1.4/ – The official Django documentation. Django has some of the best documentation out of any open source project, so don’t be scared of diving in. Be sure to check out the 4 part tutorial It covers some of the same things I did, but in much greater detail.
  2. http://www.djangobook.com/en/2.0/ – A lot of the material in the DjangoBook website is out of date, but it does a great job explaining some key concepts that are still relevant.
  3. http://www.reddit.com/r/django – The Django sub-Reddit is a great place to keep up with Django news and conversations.
  4. http://originalhaters.com/2012/07/30/mountain-lion-mamp-and-django-1-4/ – A great piece on getting Django up and running on Mountain Lion