Installing OSQA on DreamHost

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

Introduction

DreamHost is a popular hosting provider, and OSQA is known to work well there. By following these instructions you should be able to have your new OSQA site up and running in approximately 30 minutes.

The DreamHost approach to hosting Django applications is somewhat novel, but it definitely works. They use a tool called Phusion Passenger to connect your Django/Python web application to their production Apache servers. Passenger is more often used for Ruby-on-Rails solutions, but it also seems to do quite well for Python and Django.

The instructions here are largely based on DreamHost's Django instructions as well as their instructions for Passenger WSGI.

IMPORTANT: Vote for a one-click installer If you'd rather eliminate all this setup work, then vote for a DreamHost "one-click installer" for OSQA.

Step 1: Set up a shell account

If you don't already have a shell account set up for your domain, you will need to do so now. See Enabling Shell Access for details.

Step 2: Configure your domain

Next, you will need to set up your domain to use Passenger. You can do so by following these steps:

1. Open the Manage Domains section of the panel, and start editing your domain.
2. Scroll down to the "Users, Files, and Paths" section. If your web directory does not end with "/public", add that to your web directory.
3. Once you have done so, scroll down to "Web Options". Turn on the "Passenger" checkbox.
   '''NOTE''': If you currently have files under the domain, you will need to move them into the new "public" directory to make them appear!

Step 3: Create a Python 2.5 "virtualenv"

OSQA runs best on Python 2.5 or greater. DreamHost currently defaults to Python 2.4, but Python 2.5 is also available, and we recommend you use it.

The easiest way to do this is 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
python2.5 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 4: 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 DreamHost 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

Step 5: 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:
(NOTE: replace "your_domain" with the domain name you created in Step 2 above)

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

Step 6: Create a database

Every OSQA site needs a database. If you don't have one prepared already, you can create one through the panel at MySQL Databases. We strongly recommend creating a database just for OSQA (rather than sharing a database with other applications), as OSQA does not use a prefix on its table names.

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 ~/<your_domain>/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 in Step 6 when creating the database. Here's an example:

DATABASE_NAME = 'my_database'
DATABASE_USER = 'my_user'               
DATABASE_PASSWORD = 'my_password'               
DATABASE_ENGINE = 'mysql'  #mysql, etc
DATABASE_HOST = 'mysql.my_domain.com'
DATABASE_PORT = '' #leave empty for dreamhost

A little below that section you'll find another setting named APP_URL. Complete it with your fully qualified domain, (eg - "http://www.my_domain.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 ~/<your_domain>/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 the passenger_wsgi.py file

Go one level up in the directory structure

cd ..

to the domain base folder and create a file named passenger_wsgi.py file with the following content:

import sys, os
INTERP = "/home/<myusername>/bin/python"
if sys.executable != INTERP: os.execl(INTERP, INTERP, *sys.argv)
sys.path.append('/home/<myusername>/<your_domain>')
sys.path.append('/home/<myusername>/<your_domain>/osqa')
os.environ['DJANGO_SETTINGS_MODULE'] = "osqa.settings"
import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()
from paste.exceptions.errormiddleware import ErrorMiddleware
def testapplication(environ, start_response):
   status = '200 OK'
   output = 'Hello World! Running Python version ' + sys.version + '\n\n'
   response_headers = [('Content-type', 'text/plain'),
                       ('Content-Length', str(len(output)))]
   # to test paste's error catching prowess, uncomment the following line
   # while this function is the "application"
   raise("error")
   start_response(status, response_headers)
   return [output]
application = ErrorMiddleware(application, debug=True)

Replace <myusername> with your shell account username and <your_domain> with your site domain name. Make sure that you have activated passenger on your account administration panel. You van now visit your domain and create your first user, which will be your superuser.

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.