Today I had the task of installing a development server running the Django Python framework for one of our web developers. I learned a few things and I figured a quick tutorial might help someone else out. None of this covers new ground, but perhaps another telling of the story will help someone out there. I started from scratch, with a basic install of Ubuntu 7.04 Server Edition. I did not choose any extra packages, such as the LAMP option or DNS server. If you are starting off with a LAMP server already installed, or a different version, the steps will be similiar, but you may need to adapt some commands to get them to work.

Install server software

Install Apache, Mod_Python, MySQL and MySQLdb. MySQLdb is the database bindings for MySQL. Django also supports PostgreSQL, Oracle and SQLite. If you choose to use a different database server, be sure to install the appropriate Python bindings.

sudo apt-get install apache2 libapache2-mod-python
sudo apt-get install mysql-server python-mysqldb

Install the Django source code

At this point you have a couple of options. You could “apt-get install” a Django package, install an official release or install the development version. I chose to install the development version because it contains the latest bug fixes and features. We’ll be checking out the latest version from its Subversion repository. You’ll want to be in your home directory when you do this.

cd ~/

svn co http://code.djangoproject.com/svn/django/trunk/ django_src

Python won’t recognize Django unless it is installed in the “site-packages” directory, so instead we just create a symbolic link to the source code in our home directory. Run the first command to find out the path to your “site-packages” directory. Then use it in the second command, in place of “YOUR-DIR”. Lastly, copy the django-admin.py file into /usr/local/bin so that we don’t have to qualify the command with the full path to the file.

python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"

ln -s `pwd`/django_src/django YOUR-DIR/django

sudo cp ~/django_src/django/bin/django-admin.py /usr/local/bin

Create Django’s directories

Next we need to create some directories that Django will use. Once again, create these under your home directory.

cd ~/

mkdir django_projects

mkdir django_templates

mkdir media

Then we need to create some symbolic links in your webroot. The default webroot for an Apache2 installation on Ubuntu is /var/www. We are going to create a link to the media folder in your home directory, and a link to the admin_media folder which is provided in the Django source code.

cd /var/www

sudo ln -s  ~/media media

sudo ln -s ~/django_src/django/contrib/admin/media admin_media

Create a Django project

Move into your Django projects directory that we just created. We will be starting a new project using Django’s command line utility. This will give us a basic directory structure and the necessary configuration files. In my example I named the project “myproject.” Feel free to choose any name, as long as it does not conflict with any built-in Python or Django components. In particular, this means you should avoid using names like django (which will conflict with Django itself) or site (which conflicts with a built-in Python package).

cd ~/django_projects

django-admin.py startproject myproject

Edit the myproject/settings.py file and change the following sections:

1. Uncomment and change the ADMINS setting

   ADMINS = (
   
        ('Your Name', 'your_email@domain.com'),
   
   )

2. Enter your database settings. You will need your database, username and password. Most likely your database server is running on the same server, so leave DATABASE_HOST blank.

   DATABASE_ENGINE = 'mysql'           # 'postgresql_psycopg2', 'postgresql', 'mysql', 'sqlite3' or 'oracle'.
   
   DATABASE_NAME = 'django_databae'             # Or path to database file if using sqlite3.
   
   DATABASE_USER = 'you'             # Not used with sqlite3.
   
   DATABASE_PASSWORD = 'yourpassword'         # Not used with sqlite3.
   
   DATABASE_HOST = ''             # Set to empty string for localhost. Not used with sqlite3.
   
   DATABASE_PORT = ''             # Set to empty string for default. Not used with sqlite3.

3. Change your timezone if necesary.

   # Local time zone for this installation. Choices can be found here:
   
   # http://www.postgresql.org/docs/8.1/static/datetime-keywords.html#DATETIME-TIMEZONE-SET-TABLE
   
   # although not all variations may be possible on all operating systems.
   
   # If running in a Windows environment this must be set to the same as your
   
   # system time zone.
   
   TIME_ZONE = 'America/Chicago'

4. Point Django at the template directory we created.

   TEMPLATE_DIRS = (
   
    "/home/YOUR_USERNAME/django_templates"
   
       # Put strings here, like "/home/html/django_templates" or "C:/www/django/templates".
   
   )

5. Do the same thing for the media url and directory we created earlier.

   # Absolute path to the directory that holds media.
   
   # Example: "/home/media/media.lawrence.com/"
   
   MEDIA_ROOT = '/home/YOUR_USERNAME/media/'# URL that handles the media served from MEDIA_ROOT. Make sure to use a
   
   # trailing slash if there is a path component (optional in other cases).
   
   # Examples: "http://media.lawrence.com", "http://example.com/media/"
   
   MEDIA_URL = 'http://yourdomain.com/media/'

6. Set the admin media directory that we created in your webroot

   # URL prefix for admin media -- CSS, JavaScript and images. Make sure to use a
   
   # trailing slash.
   
   # Examples: "http://foo.com/media/", "/media/".
   
   ADMIN_MEDIA_PREFIX = '/admin_media/'

7. And finally, add the admin application to your install applications

   INSTALLED_APPS = (
   
       'django.contrib.auth',
   
       'django.contrib.contenttypes',
   
       'django.contrib.sessions',
   
       'django.contrib.sites',
   
       'django.contrib.admin',
   
   )

After making all those changes to the configuration we need to synchronize the Django database. You’ll also get a prompt asking you if you’d like to create a superuser account for the authentication system. Go ahead and do that.

django-admin.py syncdb

Edit the URL configuration file and uncomment the admin line. This will allow you to access the admin section later.

nano ~/django_projects/myproject/urls.py

     # Uncomment this for admin:

     (r'^admin/', include('django.contrib.admin.urls')),

Configure Apache and mod_python

In Apache2 on Ubuntu, changes to the Apache configuration are done to the /etc/apache2/httpd.conf file. We are going to configure mod_python to handle requests for the root of the site and give control to Django. However, Django doesn’t serve media files itself; it usually expects you to have a different webserver serving these files. In our case though, we want Apache to handle it, so we need to turn off mod_python for some parts of the site. You will also need to do this if you have any other folders or scripts that you want excluded from Django’s control. In my example, I have phpMyAdmin, my media folders and any URL that ends with .jpg, .gif or .png be excluded.

When deploying Django sites on mod_python, you’ll need to restart Apache each time you make changes to your Python code. However, since I’m using this as a development server, I discovered a way to avoid the hassle of having to restart the server each time. At the top of my httpd.conf, I have the line MaxRequestsPerChild 1. This forces Apache to reload everything for each request. Do not use this setting on a production server!

The only other lines you need to change are in the first <Location> block. Change “myproject.settings”, if you are using a different name for your project. Then below that be sure to change the PythonPath to point to the django_projects folder in your home directory.

sudo nano /etc/apache2/httpd.conf

MaxRequestsPerChild 1


    SetHandler python-program

    PythonHandler django.core.handlers.modpython

    SetEnv DJANGO_SETTINGS_MODULE myproject.settings

    PythonPath "['/home/YOUR_USERNAME/django_projects'] + sys.path"





    SetHandler None





    SetHandler None





    SetHandler None





    SetHandler None

Restart Apache and pray

sudo /etc/init.d/apache2 restart

You can now view your new Django website by visiting the root of the website you installed it at – http://yourdomain.com/ . You should see a Page not Found (404) error message generated by Django. Congratulations! Everything is working. You can also go to http://yourdomain.com/admin/ and log in with the superuser you created earlier.

Now that you’re done with the easy part, all thats left is to get started writing your Django apps. There is a tutorial on the official Django website that will walk you through creating an application.