Installing OSQA on WebFaction

Introduction: About This Installation Guide

This guide details the steps for setting up OSQA on a WebFaction shared-hosting account, including email setup, using Apache2, mod_wsgi, and a MySQL database backend. We have chosen arbitrary names, passwords, domain names, etc. throughout this tutorial (indicated by all caps and quotes around the name). You may choose names and passwords that are different from our suggested ones, but it is important to note that they are often referenced later in the documentation, so you must remember any alternative names and passwords that you enter.

Step 1: Setting Up a New Website in WebFaction

Signing Up

When you sign up for a Webfaction account, select Django and WebFaction will create a Django application for your website/subdomain. WebFaction will also associate that application with your website/subdomain. If necessary, add or create any domains or subdomains that you might need by going here. For the rest of this tutorial we will use "" as the domain.

Creating Your Application

Now go to the control panel and create a new Webfaction application with a "Type:" of "Django 1.2.3 (mod_wsgi 3.2/Python 2.6)". Name it "osqa_server".

Creating a Website

Next, you will need to go to this list in the Webfaction control panel and create a new Webfaction website which will associate the subdomain with the new osqa_server application. We will call the website "SITENAME" and set it to use the osqa_server application for the site's root location - "/".

Creating a Database

Typically each project you create will need its own database. This can be done here via the Webfaction control panel. Choose MySQL and modify the name (it defaults to your Webfaction account name) by adding an underscore and a project-specific identifier such as "_osqa". Before leaving this section of the control panel, you will want to change database's name and the password. We will name the database "OSQADATABASE_NAME" and "OSQADATABASE_PASSWORD" will be our password.


  • To configure email, you need to create an email mailbox. Add one here. Note that your mailbox password shouldn't be the same password you use to SSH to webfaction.
  • Save the mail password for later. We will call the username and password MAILBOX_USERNAME and MAILBOX_PASSWORD respectively. You might also consider adding an email address like, here

Step 2: Installing Required Libraries

After logging into Webfaction via SSH (go here for Webfaction's instructions), you will need to update you library files. In this tutorial we are using Python 2.6. Therefore, we will be using the command 'easy_install-2.6.' This may not be appropriate for you. For instance, if you are using Python 2.4, you need to change that command to 'easy_install-2.4'.

Required Libraries

  1. Django:
    easy_install-2.6 django
  2. HTML5:
    easy_install-2.6 html5lib
  3. Markdown
    easy_install-2.6 ElementTree
    easy_install-2.6 Markdown
  4. openidauth
    easy_install-2.6 python-openid
  5. South - automates database migrations - strongly recommended
    easy_install-2.6 South

Optional Libraries

Step 3: Getting OSQA

Now you can run the SVN command to get the software:

svn co osqa

Step 4: The Settings File

Create a Local Settings File

Now that you have the latest release of OSQA you can begin setting it up. First, change your directory to the newly formed osqa directory. Then copy and rename the file to You can do this with the following command:


Update the Database Settings

Next, you will need to open the newly created file and edit it as specified below.
DATABASE_USER = 'your_login'           
DATABASE_ENGINE = 'mysql'                      

Update the Application URL

Osqa needs to know the server domain name so that it can use that information to create URLs, such as for email validation messages. Enter your domain name in the APP_URL field as shown below:
APP_URL = 'http://YOUR_URL/' 

Step 5: The WSGI Files

Create the Local WSGI Configuration File

From within the osqa directory copy and rename the file osqa.wsgi.dist to osqa.wsgi. You can do this with the following command:

cp osqa.wsgi.dist osqa.wsgi

Update the WSGI System Paths

Now open the osqa.wsgi file and find the lines that append directories to the system's path.


These lines tell WSGI where to find the OSQA modules. You will need to update them to point to the OSQA installation directory, for instance /home/USER_NAME/webapps/osqa.

If you have not named the OSQA installation directory "osqa," you will also have to update the DJANGO_SETTINGS_MODULE value. Look for the following line, and configure it so that it looks like YOUR_OSQA_INSTALL_DIR.settings.

os.environ['DJANGO_SETTINGS_MODULE'] = 'osqa.settings'

Once you have saved your changes, the full file should look like the example below:

import os
import sys
# The first part of this module name should be identical to the directory name
# of the OSQA source.  For instance, if the full path to OSQA is
# /home/osqa/osqa-server, then the DJANGO_SETTINGS_MODULE should have a value
# of 'osqa-server.settings'.
os.environ['DJANGO_SETTINGS_MODULE'] = 'osqa.settings'
import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()

Step 6: Configure the Webserver

Open the Apache configuration file, found in /home/USER_NAME/webapps/SITE_NAME/apache2/conf/httpd.conf. Find the line where WSGIScriptAlias is defined and update it to point to the osqa.wsgi script in your OSQA installation directory. The declaration should look like this:

WSGIScriptAlias / /home/USER_NAME/webapps/SITE_NAME/PATH_TO_OSQA/osqa.wsgi

Step 7: Database

Now you will populate the blank MySQL osqa database with the necessary tables and data. From inside the OSQA directory, run the following command:

sudo python2.6 syncdb --all
You will be prompted to create a new "super user."  You should promptly answer "NO".  Once you get your site running, create a new user through the normal OSQA account creation process and that will be your super user.

With that command you have successfully defined the schema. With South installed, you also have the ability to migrate between databases--a useful feature as OSQA is updated. However, as this is a fresh install, you will need to convince South that the schema is already up to date by "faking" a migration. You can do that with the following command:

sudo python2.6 migrate forum --fake

Step 8: Starting & Stopping Your Server

With the database now prepared, you are ready to start the Apache server and begin using your new OSQA installation.

To get your server up and running, enter the following into the command shell:

You can see the results of the Apache start and stop commands by looking at the log held in /home/USER_NAME/logs/user/error_SITE_NAME.log.

Step 9: Setting up Your First User and Standardizing the Interface

Once you get into your site you're going to setup your first user which will be you and it will automatically make you a superuser. When you're done registering you'll see the link for the administration panel in the upper left corner. Once you get into the admin area click on To Standard Interface in the upper left corner to get rid of the ugly simple text version.

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.