Installing OSQA on WebFaction

{toc}

h2. Introduction: About This Installation Guide

This guide details the steps for setting up OSQA on a [WebFaction shared-hosting account|http://www.webfaction.com?affiliate=osqa], 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.

h2. Step 1: Setting Up a New Website in WebFaction

h4. Signing Up
When you [sign up for a Webfaction account|http://www.webfaction.com?affiliate=osqa], 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|https://panel.webfaction.com/domain/list/]. For the rest of this tutorial we will use "DOMAIN.com" as the domain.

h4. Creating a Database
Typically each project you create will need its own database. This can be done [here|https://panel.webfaction.com/database/create] 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.

h4. Email
* To configure email, you need to create an email mailbox. Add one [here|https://panel.webfaction.com/mailbox/list]. 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|https://panel.webfaction.com/email/list]


h2. Step 2: Installing Required Libraries

After logging into Webfaction via SSH (go [here|http://docs.webfaction.com/user-guide/access.html?highlight=ssh#connecting-with-ssh] 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'.

h4. Required Libraries

# Django:
{code:borderStyle=none}
easy_install-2.6 django
{code}
# HTML5:
{code:borderStyle=none}
easy_install-2.6 html5lib
{code}
# Markdown
{code:borderStyle=none}
easy_install-2.6 ElementTree
easy_install-2.6 Markdown
{code}
# openidauth
{code:borderStyle=none}
easy_install-2.6 python-openid
{code}
# [South|http://south.aeracode.org/] \- automates database migrations - _strongly recommended_
{code:borderStyle=none}
easy_install-2.6 South
{code}

h4. Optional Libraries

* djangosphinx - only necessary if you are going to use the sphinxfulltext module. (refer back to the [Modules|http://wiki.osqa.net/display/docs/OSQA+Installation+and+Upgrade+Guides] section for more details)
[http://sphinxsearch.com/downloads.html]
[http://github.com/dcramer/django-sphinx/tree/master/djangosphinx]
* [Django Debug Toolbar|http://github.com/robhudson/django-debug-toolbar] \- very helpful for debugging
{code:borderStyle=none}
easy_install-2.5 django-debug-toolbar
{code}

h2. Step 3: Getting OSQA
Now you can run the SVN command to get the software:

{code:borderStyle=none}
svn co http://svn.osqa.net/svnroot/osqa/trunk/ osqa
{code}

h2. Step 4: The Settings File

h4. 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:

{code:borderStyle=none}
cp settings_local.py.dist settings_local.py
{code}

h4. Update the Database Settings

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

{code:title=settings_local.py|borderStyle=solid}
DATABASE_NAME = 'DATABASE_NAME'
DATABASE_USER = 'your_login'
DATABASE_PASSWORD = 'DATABASE_PASSWORD'
DATABASE_ENGINE = 'mysql'
{code}

h4. 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:

{code:title=settings_local.py|borderStyle=solid}
APP_URL = 'http://YOUR_URL/'
{code}

h2. Step 5: The WSGI Files

h4. 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:

{code:borderStyle=none}
cp osqa.wsgi.dist osqa.wsgi
{code}

h4. Update the WSGI System Paths

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

{code:borderStyle=none}
sys.path.append('/path/to_dir_above')
sys.path.append('/path/to_dir_above/osqa')
{code}

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}}.

{code:borderStyle=none}
os.environ['DJANGO_SETTINGS_MODULE'] = 'osqa.settings'
{code}

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

{code:title=osqa.wsgi|borderStyle=solid}
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()
{code}

h2. Step 6: Configure the Webserver

h2. 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:

{code:borderStyle=none}
sudo python2.6 manage.py syncdb --all
{code}

{warning:title=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.
{warning}

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:

{code:borderStyle=none}
sudo python2.6 manage.py migrate forum --fake
{code}

h2. 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:

{code:borderStyle=none}
~/webapps/osqa_server/apache2/bin/stop
~/webapps/osqa_server/apache2/bin/start
{code}

{tip}
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}}.
{tip}

h2. 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.