Installing OSQA on Site5 with fast-cgi

Be careful, this is an early draft This is an early draft of the instructions for installing OSQA on Site5.com. It may be incomplete and is not yet fully tested. It is a work-in-progress.

Introduction

This recipe will show you how to install OSQA on your shared hosting account at Site5.com - a professional hosting company which offers low-cost hosting accounts capable of running OSQA. We have used this exact recipe to set up a simple OSQA demo site at http://site5.osqa.net.

Step 1: Enable SSH

You'll need to enable SSH access on your Site5 account. Go to the SiteAdmin control panel, click "Advanced Tools -> Get Shell Access" and click "Enable Shell Access" on your account. Go ahead and use your preferred SSH terminal program to connect to your Site5 account. You'll be using this connection shortly.

Critical Step: Get "bash" shell access Your Site5 SSH login will default to a heavily restricted "jailshell", and you must file a support ticket with Site5 to request that they switch your account to use the "bash" shell instead. Until they do this, you cannot proceed any further.

Step 2: Create a Python 2.6 "virtualenv"

Now you need to set up a "virtual environment" for Python using virtualenv. Virtualenv allows you to add and modify Python modules without access to the global installation. As of May 2010 1.4.9 is the latest, please check here for a newer version.

SSH into your server, and run these commands:

wget http://pypi.python.org/packages/source/v/virtualenv/virtualenv-1.4.9.tar.gz
tar xzf virtualenv-1.4.9.tar.gz
python2.6 virtualenv-1.4.9/virtualenv.py $HOME/local
rm -rf virtualenv*
export PATH=$HOME/local/bin:$PATH

When you login again later, you'll need to make sure your path gives preference to ~/local/bin before /usr/bin so that your "local" copy of Python runs, and that your scripts refer to that location. That's what the line "export PATH=$HOME/local/bin:$PATH" accomplishes. You may want to create .bashrc and/or .bash_profile files like the following (or add these lines to your existing files):

export PATH=$HOME/local/bin:$PATH

if [ -f ~/.bashrc ]; then
   source ~/.bashrc
fi

Now that you have configured virtualenv, you can run easy_install to install Python modules.

Step 3: Install the required Python libraries

OSQA depends on certain required Python libraries and uses others that we strongly recommend. In this section we will install these libraries into your Site5 account. While still connected to your SSH terminal session, run these commands:

easy_install django
easy_install flup
easy_install html5lib
easy_install markdown
easy_install python-openid
easy_install South
easy_install django-debug-toolbar
easy_install mysql-python

Step 4: Get the OSQA source code from subversion

You'll get the latest and greatest OSQA source code directly from the project's Subversion repository. It's pretty easy to do. While we're at it, we'll also make log and temporary directories writable. In the same SSH terminal session, run these commands:

svn co http://svn.osqa.net/svnroot/osqa/trunk/ ~/osqa
chmod 777 ~/osqa/tmp
chmod 777 ~/osqa/log

Step 5 (optional): Create a web directory for your subdomain

If you will be running OSQA on a subdomain that is different from your Site5 account's main domain, then you will need to create and configure the subdomain's web documents directory. Simply use your SSH terminal to create a new directory somewhere (usually inside your public_html directory.) This directory will be the root of your web documents for the Apache webserver.

mkdir ~/public_html/myosqa

Now visit "Manage My Domains -> Subdomains" on the Site5 SiteAdmin and use the tools to add your desired subdomain and point it at the new directory you just created.

Step 6: Create a database

Your Site5 OSQA site will be using MySQL as its database. In the Site5 SiteAdmin, select "MySQL Database -> Manage Databases." Enter the name you want in the "Create MySQL database" section (it will be prefixed by your username), and click the "Create MySQL database" button.

Click back to the Site5 SiteAdmin and select "MySQL Databases - > Manage Users" to create a new user and grant that user full access to the MySQL database you just created.

Step 7: Edit the Django settings file

Now you need to tell OSQA which database and which domain to use. In your SSH terminal window switch into your OSQA installation directory, copy the file settings_local.py.dist to settings_local.py, and then use pico or vim to edit it:

cd ~/osqa
cp settings_local.py.dist settings_local.py
nano settings_local.py

Locate the section where database settings go, and complete it with the values you used above when creating the database. Here's an example:

DATABASE_NAME = 'my_database'
DATABASE_USER = 'my_user'
DATABASE_PASSWORD = 'my_password'
DATABASE_ENGINE = 'mysql'
DATABASE_HOST = 'localhost'
DATABASE_PORT = '' #leave empty for Site5

A little below that section you'll find another setting named APP_URL. Enter your fully qualified domain, (eg - "http://osqa.yourdomain.com".) Save the file and exit the editor.

Step 8: Prepare the database for OSQA

Now it is time to create and populate the various database tables OSQA and Django need. Use your SSH terminal window to run these commands:

cd ~/osqa
python manage.py syncdb --all
python manage.py migrate forum --fake

When prompted to create a new user, just say no.

Step 9: Create your .htaccess and FastCGI script

In your web directory (defaults to ~/public_html), add the following to a file named .htaccess:

AddHandler fcgid-script .fcgi
RewriteEngine On

RewriteCond %{HTTP_HOST} !^yoursite.com$ [NC]
RewriteRule ^(.*)$ http://yoursite.com/$1 [R=301,L]

RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ osqa.fcgi/$1 [QSA,L]

Then, create a small script that tells Apache how to spawn your FastCGI program. Create a file osqa.fcgi inside your web directory:

#!/home/<USERNAME>/local/bin/python
import os, sys

_PROJECT_DIR = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))), 'osqa')
sys.path.insert(0, _PROJECT_DIR)
sys.path.insert(0, os.path.dirname(_PROJECT_DIR))

_PROJECT_NAME = _PROJECT_DIR.split('/')[-1]
os.environ['DJANGO_SETTINGS_MODULE'] = "%s.settings" % _PROJECT_NAME

from django.core.servers.fastcgi import runfastcgi
runfastcgi(method="threaded", daemonize="false")

Replace <USERNAME> in the first line with your own Site5 username.

Now be sure to make your .fcgi file executable. In your SSH terminal window type:

chmod +x ~/public_html/osqa.fcgi

Step 10: Enjoy your new OSQA site!

If you have followed all the previous steps, then you should be proud to visit your domain's URL in your favorite web browser and see your new OSQA site up and running. If it is, congratulations and well done! If not, just retrace all your steps and be sure you didn't miss anything. Feel free to come visit us in the OSQA chat channel, and we'll be happy to try to help.

Note: Restarting the spawned server

If you change any Python code on your site, you'll need to tell FastCGI the code has changed. But there's no need to restart Apache in this case. Rather, just touch osqa.fcgi, or edit the file, so that the timestamp on the file will change. When Apache sees the file has been updated, it will restart your Django application for you.

If you have access to a command shell on a Unix system, you can accomplish this easily by using the touch command:

touch ~/public_html/osqa.fcgi