Getting Started with Django

See also

Watch this screencast to see a brief demo of setting up a Django application:

In this guide, you’ll learn to set up a Django site on WebFaction by:

  • creating a website entry with the control panel,
  • installing applications for Django and static media,
  • creating a PostgreSQL database, and
  • configuring Django.

When you’re finished, you’ll be well on your way to making a functioning Django-base web application.

Create a Website with Django and Static Media Applications

The first step is to create a website with applications for Django and serving static media. We’re going to use a separate application for static media, instead of using Django, to reduce memory consumption.

  1. Log in to the control panel.

  2. Click Domains / websites ‣ Websites. The list of websites appears.

  3. Click the Add new website button. The Create a new website form appears.

  4. In the Name field, enter a website name.

  5. If applicable, in the Machine menu, click to select the server to host the website.

  6. If applicable, in the IP address menu, click to select the IP address to serve the site.

  7. For each domain name you want to use with the website, add it to the list of domains.

    In the Domains field, enter the domain name. Enter one or more domain names. If the domain has not yet been added to the control panel, click the Create link that appears at the bottom of the list of domains to add it.

  8. Add the Django application.

    1. Click Add an application ‣ Create a new application. The Create a new web app form appears.
    2. In the Name field, enter a name for the Django application.
    3. In the App category menu, click to select Django.
    4. Click the Save button. The Django application is installed and added to website’s list of applications.
  9. Create the static media application.

    1. Click Add an application ‣ Create a new application. The Create a new web app form appears.
    2. In the Name field, enter a name for the static media application.
    3. In the App category menu, click to select Static.
    4. In the App type menu, click to select Static only (no .htaccess).
    5. In the URL field, enter static.
    6. Click the Save button. The static media application is installed and added to the website’s list of applications.
  10. Click the Save button. The website is created and added to the list of websites.

Creating a Database

Next, create a database and database user.

  1. Click Databases ‣ Databases. The list of databases appears.

  2. Click the Add new database button. The Create a new database form appears.

  3. In the Name field, enter a name for the database.

  4. In the Database type menu, click to select PostgreSQL.

  5. Choose a database owner.

    To choose an existing user, in the Database owner menu, click to select a username.

    To create a new user:

    1. In the Database owner menu, click to select Create a new postgresql user. Username, Password, and Confirm Password fields appear.

    2. In the Username field, enter a username.

    3. In the Password field, enter a password.

      See also

      See Strengthening Passwords for important information about choosing passwords.

    4. In the Confirm Password field, reenter the password.

  6. Click the Save button.

The database is created and appears in the list.

Configuring Django

Now, configure the Django application to use the static media application, send email, and connect to the database.

Note

Do you have your own project ready to go or do you want to start a project with a name other than the default? To substitute myproject by creating a new project or uploading your own:

  1. Open an SSH session to your account.

  2. Enter cd $HOME/webapps/django_app, where django_app is the name of the Django application as it appears on the control panel, and press Enter.

  3. Enter rm -rf ./myproject and press Enter.

  4. If applicable, upload your project directory to $HOME/webapps/django_app.

    Otherwise, enter ./bin/django-admin.py startproject project.

  5. Open $HOME/webapps/django_app/apache2/conf/httpd.conf in a text editor.

  6. Change the WSGIDaemonProcess‘s python-path option. Replace this line:

    WSGIDaemonProcess <django_app> processes=2 threads=12 python-path=/home/<username>/webapps/<django_app>:/home/<username>/webapps/<django_app>/myproject:/home/<username>/webapps/<django_app>/lib/<python>
    

    with this line:

    WSGIDaemonProcess <django_app> processes=2 threads=12 python-path=/home/<username>/webapps/<django_app>:/home/<username>/webapps/<django_app>/<project>:/home/<username>/webapps/<django_app>/lib/<python>
    

    where

    • <django_app> is the name of Django application,
    • <username> is your username,
    • <python> is the Python version associated with the application (for example, python2.7), and
    • <project> is the name of your Django project.
  7. Change WSGIScriptAlias / /home/username/webapps/django_app/myproject/myproject/wsgi.py to WSGIScriptAlias / /home/username/webapps/django_app/project/project/wsgi.py.

  8. Save your changes and close the file.

Be sure to update your Django settings to use your new database and media applications.

  1. Open an SSH session to your account.

  2. In a text editor, open /home/username/webapps/django_app/project/project/settings.py, where django_app is the name of the application as it appears on the control panel and project is the name of Django project (myproject, by default).

  3. Set ALLOWED_HOSTS to a list of host names where your Django site is expected to run. For example, if you site is being served at example.com and www.example.com, then your ALLOWED_HOSTS setting should look like this:

    ALLOWED_HOSTS = [
        'example.com',
        'www.example.com',
    ]
    

    Alternatively, you can specify a subdomain wild card with a leading period. For example, to permit any subdomain of example.com, then ALLOWED_HOSTS would look like this:

    ALLOWED_HOSTS = [
        '.example.com',
    ]
    

    As a security precaution, this setting is required for your Django site to run with DEBUG = False.

Configuring Django to Connect to a Database

While continuing to edit /home/username/webapps/django_app/project/project/settings.py:

  1. Update the DATABASES 'default' dictionary:

    1. Set ENGINE to 'django.db.backends.postgresql_psycopg2'.
    2. Set NAME to a string containing the database name you specified in Creating a Database.
    3. Set USER to a string containing the database username you specified in Creating a Database.
    4. Set PASSWORD to a string containing the database user’s password.
    5. Set HOST to '127.0.0.1'.
    6. Set PORT to '5432'.

    When you’re finished, your DATABASES settings will look something like this:

    DATABASES = {
        'default': {
            'ENGINE': 'django.db.backends.postgresql_psycopg2',
             'NAME': 'django_db',
             'USER': 'django_db',
             'PASSWORD': 'mysecret',
             'HOST': '127.0.0.1',
             'PORT': '5432',
        }
    }
    

Configuring Django to Serve Static Media

While continuing to edit /home/username/webapps/django_app/project/project/settings.py:

  1. If applicable, specify the paths for additional static media.

    Django automatically includes your INSTALLED_APPS‘s static files (for example, the Django admin media or the files in someapp/static), but if you want to include additional directories of static files, set STATICFILES_DIRS to a tuple of directory paths.

    For example, you might add lines like this:

    STATICFILES_DIRS = (
        '/home/<username>/src/extra_static_media/',
        '/home/<username>/webapps/<django_app>/even_more_static_media/',
    )
    
  2. Configure Django to collect static media in your static media application’s directory.

    Set STATIC_ROOT to '/home/username/webapps/static_media_app/' where static_media_app is the name of the static media application.

Configuring Django to Send Email Messages

While continuing to edit /home/username/webapps/django_app/project/project/settings.py:

  1. Set recipients of error notifications. On a new line, set ADMINS to a tuple of tuples containing names and email addresses of notification recipients. For example, insert ADMINS = (('Jane', 'jane@example.com'), ('John', 'john@example.com')).
  2. Set the host name of the SMTP server. On a new line, add EMAIL_HOST = 'smtp.webfaction.com'.
  3. Set the SMTP user name. On a new line, add EMAIL_HOST_USER = 'mailbox', where mailbox is a valid mailbox name.
  4. Set the SMTP password. On a new line, add EMAIL_HOST_PASSWORD = 'password', where password is the mailbox’s password.
  5. Set the From (origin) email address. On a new line, add SERVER_EMAIL = 'address', where address is the sending email address.
  6. Save and close settings.py.

Synchronizing the Database and Storing Static Files

Now, use manage.py to store your static files and synchronize the database.

  1. Change to the project directory. Enter cd /home/username/webapps/django_app/project and press Enter.
  2. Enter pythonX.Y manage.py migrate and press Enter. The database will be updated. You may be prompted to create a superuser; if so, create one now.
  3. Enter pythonX.Y manage.py collectstatic and press Enter. Static files for installed apps and files in STATICFILES_DIRS are copied to your static media application.

Restarting Apache

The final stage of the process is to restart Apache.

  1. Change to Apache’s bin directory. Enter cd /home/username/webapps/django_app/apache2/bin and press Enter.
  2. Enter ./restart and press Enter.

You can now open http://domain/admin and admire your admin site.

See also

If you run into any problems with your new Django application, see Django Troubleshooting.