Installing OSQA on AlwaysData

Be careful, this is an early draft This is an early draft of the instructions for installing OSQA on AlwaysData. 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 AlwaysData - a popular provider which offers both free and low-cost hosting accounts capable of running OSQA. We have used this exact recipe to set up a simple OSQA demo site at http://alwaysdata.osqa.net.

Step 1: Enable SSH

You'll need to enable SSH access on your AlwaysData account. Go to the web-based admin panel, click "Remote Access -> SSH" and enable SSH login on your account. Go ahead and use your preferred SSH terminal program to connect to your AlwaysData account. You'll be using this connection shortly.

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 April 2010 1.4.8 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.8.tar.gz
tar xzf virtualenv-1.4.8.tar.gz
python virtualenv-1.4.8/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 AlwaysData account. While still connected to your SSH terminal session, run these commands:

easy_install django
easy_install html5lib
easy_install markdown
easy_install python-openid
easy_install south
easy_install django-debug-toolbar
easy_install mysql-python
easy_install psycopg2

Note: You don't actually need both mysql-python and psycopg2. Technically, you only need the one which corresponds to the database you intend to use.

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: Create and configure your web directory

Create a new directory inside the one where you just downloaded OSQA. This will be the root of your web documents for the Apache webserver.

mkdir ~/osqa/public

Now, using the AlwaysData web admin, visit "Domains" and add (or edit) your domain to point to the path /osqa/public/ (which we will later refer to as your web directory.)

Step 6: Create a database

AlwaysData makes both PostgreSQL and MySQL databases available. We'll use PostgreSQL in this example, but you can select whichever you prefer. In the web admin, select "Databases -> PostgreSQL" and click "Add database." Enter the name you want for your database (it will be prefixed by your username), select UTF8 encoding, and click the Submit button.

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
pico 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 = 'postgresql_psycopg2' #mysql, if using MySQL
DATABASE_HOST = 'postgresql.alwaysdata.com' #mysql.alwaysdata.com, if using MySQL
DATABASE_PORT = '' #leave empty for AlwaysData

A little below that section you'll find another setting named APP_URL. Enter your fully qualified domain, (eg - "http://osqa.alwaysdata.net".) 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 (should be ~/osqa/public), add this to a file named .htaccess:

 
AddHandler fcgid-script .fcgi
RewriteEngine On
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.dirname(os.path.dirname(os.path.abspath(__file__)))
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 AlwaysData username.

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

chmod +x ~/osqa/public/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 ~/osqa/public/osqa.fcgi