I’ve been thinking about writing a start-to-finish Django tutorial, creating a simple CMS for a hierarchical web site going from installation of Django on a clean system all the way to a CMS that automatically uploads web pages to a remote web server. It will probably be a while before I get started on that (if I ever do) but I got the opportunity to do a clean Django install yesterday on a new iMac.

Out of the box (as this iMac was) Mac OS X 10.5 (Leopard) has everything you need to start using Django except Django itself. It has Python 2.5, and it has SQLite 3 for storing data. The only thing I installed on the iMac before installing Django was Smultron, because I wanted a nice GUI text editor for editing the configuration files.

There are three steps to setting up Django: installing it, starting a project, and setting up a database to store your web applications.

Install Django on Leopard

1. Log in to your administrative account if you don’t normally work from an administrative account (by default, you do: the first account on Mac OS X is administrative).
2. Download “latest official version” of Django (0.96.1 as I write this). It will be a “tar” file.
3. Click the file once in your downloads stack to unarchive it (Django-0.96.1.tar).
4. Open the terminal (if you don’t have it on your dock, add it to your dock from the Utilities folder in Applications)
5. Type “cd ” (that’s “cd” with a space) in the terminal window.
6. Drag the folder you created from the tar file (Django-0.96.1) from the stack onto the terminal window.
7. Press return in terminal. This moves you into the Django installation folder.
8. Type “sudo python setup.py install”. It will ask for your administrative password when you press return.

At this point, Django is mostly installed, but you do need to cover for a broken installation process:

1. In the downloads stack, open the Django-0.96.1 folder, go into django, contrib, and then admin.
2. Open a new Finder Window and go into your hard drive, Library, Python, 2.5, site-packages, django, contrib, and admin.
3. Drag media and templates from the first folder to the second folder.

Django is now installed. You can leave your administrative account and go to the account you normally use if it is different from your administrative account.

Start a project in Django

A project in Django can contain many web applications.

1. Open your Documents folder.
2. Make a new folder; call it something like “Django Projects”.
3. Open the terminal if it isn’t still open.
4. Type “cd ” (again, “cd” with a trailing space).
5. Drag the folder you just created into the terminal.
6. Press return in the terminal window.
7. Type “django-admin.py startproject CMS”.
8. Look in the Django Projects folder for the newly created CMS folder.

You now have a Django project created. You can now tell Django to start a web server, and you can view that web server in Safari.

1. In the same terminal window, type “cd CMS”.
2. Type “python manage.py runserver”.
3. Go into Safari (or any web browser) and go to the URL “http://localhost:8000/”
4. It should now say “It worked!” and congratulate you.

You might want to bookmark this page. Try loading it a couple of times and watch the terminal: every time you load the page, you’ll see a corresponding line added to the terminal. This will become very useful once you start creating web applications.

Set up a database for Django

Django can use several databases, and if you’re familiar with one of the ones it uses, go ahead and set it up. But if not, you can use the SQLite database software built in to Mac OS X.

1. In your Project directory, find “settings.py” and open it in Smultron (or any text editor).
2. In between the single quotes after DATABASE_ENGINE, type “sqlite3”. It should look like “DATABASE_ENGINE = 'sqlite3'”.
3. In between the single quotes after DATABASE_NAME, type “MyCMS.sqlite3”. It should look like “DATABASE_NAME = 'MyCMS.sqlite3'”.
4. Open a new window in the terminal, and cd to your CMS folder (type “cd ” and drag the CMS folder onto the terminal).
5. Type “python manage.py syncdb”.
6. Type “yes” to create a superuser.
7. Type a username (it will default to your username on your Mac, which is fine).
8. Type an e-mail address.
9. Choose a password and remember it!
10. In the settings.py file, towards the end, look for a line that says “INSTALLED_APPS”.
11. Directly below “django.contrib.sites”, add a line that looks the same except that it will be “'django.contrib.admin',”. That section should now look like:

    [toggle code]

    • INSTALLED_APPS = (
      • 'django.contrib.auth',
      • 'django.contrib.contenttypes',
      • 'django.contrib.sessions',
      • 'django.contrib.sites',
      • 'django.contrib.admin',
    • )
12. Type “python manage.py syncdb” in the terminal again.
13. Open urls.py in Smultron and remove the hash mark in front of the line that “includes” django.contrib.admin.urls.

This sets up the database for you and creates an authorization database for you to use. Go to “http://localhost:8000/admin/” and click on Users. You will see the admin user you created as part of this step.

If you look in the CMS folder of your Django Projects folder you’ll see the newly-created “MyCMS.sqlite3” database file. Once you start using Django, this is where all of your data will be stored, so you’ll want to back this file up regularly.

Playing around

You should now be able to follow along with the samples in various places on the web (such as the Django web site itself and Jeff Croft’s Django for non-programmers). Remember that you can use CONTROL-C in the terminal that has runserver running to quit your project. Whenever you want to start the project up again, go back to that folder in terminal and type the “runserver” command in the “start a project” section above.