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 "DOMAIN.com" 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.

Email

  • 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 admin@DOMAIN.com, 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 http://svn.osqa.net/svnroot/osqa/trunk/ 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 settings_local.py.dist to settings_local.py. You can do this with the following command:

cp settings_local.py.dist settings_local.py

Update the Database Settings

Next, you will need to open the newly created settings_local.py file and edit it as specified below.

settings_local.py
DATABASE_NAME = 'DATABASE_NAME'
DATABASE_USER = 'your_login'           
DATABASE_PASSWORD = 'DATABASE_PASSWORD'
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:

settings_local.py
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.

sys.path.append('/path/to_dir_above')
sys.path.append('/path/to_dir_above/osqa')

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:

osqa.wsgi
import os
import sys
sys.path.append('/home/USER_NAME/webapps')
sys.path.append('/home/USER_NAME/webapps/osqa')
# 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 manage.py syncdb --all
Warning
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 manage.py 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:

~/webapps/osqa_server/apache2/bin/stop
~/webapps/osqa_server/apache2/bin/start
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.
  1. May 20, 2010

    Vaughan says:

    Add to the end of Step 1: Add symbolic link to the static admin media directory...

    Add to the end of Step 1:

    Add symbolic link to the static admin media directory.
    Static means this content does not require any code to run to generate it. This includes images, javascript and css.

    OSQA expects the media for the admin panel to be located in XXX.webfactional.com/admin_media/

    This media is actually located at /home/XXX/webapps/osqa_server/lib/python2.5/django/contrib/admin/media

    Follow the instructions here (http://docs.webfaction.com/software/django.html) in the section "Serving Admin Media" and in the extra info field enter the following (with XXX replaced with your home directory name, of course) "/home/XXX/webapps/osqa_server/lib/python2.5/django/contrib/admin/media"

  2. Jul 04, 2010

    Tim Monn says:

    Edit for Step 7: The Settings File There's an issue with the DATABASE_USER, sin...

    Edit for Step 7: The Settings File

    There's an issue with the DATABASE_USER, since on Webfaction the each database is isolated on its own database user account:

    DATABASE_NAME = 'DATABASE_NAME'
    DATABASE_USER = 'your_login'
    DATABASE_PASSWORD = 'DATABASE_PASSWORD'

    Should be:

    DATABASE_NAME = 'DATABASE_NAME'
    DATABASE_USER = 'DATABASE_NAME'
    DATABASE_PASSWORD = 'DATABASE_PASSWORD'

  3. Aug 21, 2010

    Zachary Bricker says:

    A few idiosyncrasies with the article. GROUP_NAME - is undefined as to what sho...

    A few idiosyncrasies with the article.

    GROUP_NAME - is undefined as to what should be placed there.

    NameVirtualHost 127.0.0.1:PORT_NUMBER - seems to serve no purpose, or perhaps I missed a step?

    The installation directions are not very concise. I've been through them about 3 times, making sure I'm making the proper changes and I still can't get this to work on webfaction.

    1. Aug 22, 2010

      Michael says:

      The wiki post above is slightly out of date. GROUP_NAME is your username, and th...

      The wiki post above is slightly out of date. GROUP_NAME is your username, and the NameVirtualHost line can be skipped. See this thread

  4. Jan 27, 2011

    Emil F. says:

    There is an easier way to install OSQA on WebFaction now. Simply use the install...

    There is an easier way to install OSQA on WebFaction now. Simply use the install script from http://wiki.webfaction.com/wiki/InstallScripts

    1. Apr 13, 2011

      James Spittal says:

      Just tried the latest OSQA install script as of today and received the following...

      Just tried the latest OSQA install script as of today and received the following error message:

      "Error: Traceback (most recent call last):
      File "/var/tmp/api_system.48940", line 92, in ?
      fn_mapper[action](api,app_name,db_name)
      File "/var/tmp/api_system.48940", line 55, in create
      api.system(ez_install_cmd + lib)
      File "/usr/lib/python2.4/site-packages/webfaction/api/_init_.py", line 105, in system
      raise APIError(e.faultString)
      webfaction.api.APIError: Error while executing system commands:
      /var/tmp/api_system.24274: line 1: 1html5lib: ambiguous redirect"

      1. Apr 13, 2011

        Emil F. says:

        Sorry abut this, I inadvertently broke the script with my last update. It is now...

        Sorry abut this, I inadvertently broke the script with my last update. It is now fixed.

        On a side note, you would get a faster reaction if you report this kind of problems to the WebFaction support.

        1. Apr 13, 2011

          James Spittal says:

          No worries. Working now. Thanks for the fix.

          No worries. Working now. Thanks for the fix.

  5. Jan 10, 2012

    Bryce Nesbitt says:

    Select "Django 1.2.3 (mod_wsgi 3.2/Python 2.6)" should read "Select the most rec...

    Select "Django 1.2.3 (mod_wsgi 3.2/Python 2.6)" should read "Select the most recent 1.2.x series Django". There's no reason to have a version with security flaws.

    Is this page a true Wiki... can we edit it?