INSTALL

CONTENTS
------------------
A. PREREQUISITES
B. INSTALLATION
   1. Settings file
   2. Database
   3. Running OSQA in the development server
   4. Installation under Apache/WSGI
   5. Email subscriptions
C. CONFIGURATION PARAMETERS (settings_local.py)
D. CUSTOMIZATION


A. PREREQUISITES
-----------------------------------------------
0. We recommend you to use python-setuptools to install pre-requirement libraries.
If you haven't installed it, please try to install it first.
e.g, sudo apt-get install python-setuptools

1. Python2.5/2.6, a rdbm (such as MySql or PostgreSql), Django v1.0/1.1
Note: email subscription sender job requires Django 1.1, everything else works with 1.0
Make sure you have the necessary support for python to communicate with your rdbm.
sudo easy_install mysql-python (for MySql)
sudo easy_install postgresql_psycopg2 (for PostgreSql)

2. html5lib
http://code.google.com/p/html5lib/
Used for HTML sanitizer
sudo easy_install html5lib

3. Markdown2
http://code.google.com/p/python-markdown2/
sudo easy_install markdown2

4. Optional, but highly recommended, you may want to install south from http://south.aeracode.org/ , it will make upgrades a lot easier.


5. Also optionally you may want to install Django Debug Toolbar for debugging.
This is not required and OSQA will just ignore it if you don't have it.
http://github.com/robhudson/django-debug-toolbar/tree/master

6. Depending on which modules you decide to enable (see bellow for more info on modules),
you may need to install some aditional dependencies. Here's a list of the dependencies of each bundled module if any:

    a) openidauth, depends on Python-openid
       http://openidenabled.com/python-openid/

    b) sphinxfulltext, depends on djangosphinx, and obviously you'll have to install the sphinx search engine
       http://sphinxsearch.com/downloads.html
       http://github.com/dcramer/django-sphinx/tree/master/djangosphinx



B. INSTALLATION
-----------------------------------------------
0. Make sure you have all above python libraries installed.

   make osqa installation server-readable on Linux command might be:
   chown -R yourlogin:apache /path/to/OSQA

   directories templates/upfiles and log must be server writable

   on Linux type chmod
   chmod -R g+w /path/to/OSQA/upfiles
   chmod -R g+w /path/to/log

   above it is assumed that webserver runs under group named "apache"

1. Settings file

Copy settings_local.py.dist to settings_local.py and
update all your settings. Check settings.py and update
it as well if necessory.
Section C explains configuration paramaters.

1b. Modules

Decide which modules you want to DISABLE. Each module adds a specific piece of functionality to OSQA, and
by default, all are enabled, you have to disable the ones you want. If any module doesn't meet the required dependencies it just
won't load.
Currently bundled modules are:

    localauth - provides local authentication and registration on your site, disable this if you want only external login
                through any external provider

    openidauth - adds support for open id on osqa and adds some openid providers to the signin page

    oauthauth - adds support for oauth authentication on osqa and adds twitter as a signin provider on the signin page

    facebookauth - adds facebook as an authentication provider

    pgfulltext - adds support to full text search functionality through postgresql if you're useing it as your rdbm

    sphinxfulltext - adds support for full text search with the sphinx search engine
                     (detailed instructions are in the module root folder)

    robotstxt - adds a robots file editable throug the admin interface

    recaptcha - adds support for recaptcha in the registration form

    default_badges - the default set of badges, others can be added or used instead

    books - don't really does anything, it's disabled by default, and you should keep it that way, you can delete it if you want to


2. Database

Prepare your database by using the same database/account
configuration from above.
e.g,
create database osqa DEFAULT CHARACTER SET UTF8 COLLATE utf8_general_ci;
grant all on osqa.* to 'osqa'@'localhost';
And then run "python manage.py syncdb" to synchronize your database.

If you're using south, then run "python manage.py migrate forum 0001 --fake".

When you're prompted to create a new superuser, 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.

3. Running OSQA on the development server

Run "python manage.py runserver" to startup django
development environment.
(Under Linux you can use command "python manage.py runserver `hostname -i`:8000",
where you can use any other available number for the port)

4. Installation under Apache/WSGI

4.1 Prepare wsgi script

Make a file readable by your webserver with the following content:

---------
import os
import sys

sys.path.insert(0,'/one/level/above') #insert to make sure that forum will be found
sys.path.append('/one/level/above/OSQA') #maybe this is not necessary
os.environ['DJANGO_SETTINGS_MODULE'] = 'OSQA.settings'
import django.core.handlers.wsgi
application = django.core.handlers.wsgi.WSGIHandler()
-----------

insert method is used for path because if the forum directory name
is by accident the same as some other python module
you wull see strange errors - forum won't be found even though
it's in the python path. for example using name "test" is
not a good idea - as there is a module with such name


4.2 Configure webserver
Settings below are not perfect but may be a good starting point

---------
WSGISocketPrefix /path/to/socket/sock #must be readable and writable by apache
WSGIPythonHome /usr/local #must be readable by apache
WSGIPythonEggs /var/python/eggs #must be readable and writable by apache

#NOTE: all urs below will need to be adjusted if
#settings.FORUM_SCRIPT_ALIAS !='' (e.g. = 'forum/')
#this allows "rooting" forum at http://example.com/forum, if you like
<VirtualHost ...your ip...:80>
    ServerAdmin forum@example.com
    DocumentRoot /path/to/osqa-site
    ServerName example.com

    #run mod_wsgi process for django in daemon mode
    #this allows avoiding confused timezone settings when
    #another application runs in the same virtual host
    WSGIDaemonProcess OSQA
    WSGIProcessGroup OSQA

    #force all content to be served as static files
    #otherwise django will be crunching images through itself wasting time
    Alias /m/ /path/to/osqa-site/forum/skins/
    Alias /upfiles/ /path/to/osqa-site/forum/upfiles/
    <Directory /path/to/osqa-site/forum/skins>
        Order deny,allow
        Allow from all
    </Directory>

    #this is your wsgi script described in the prev section
    WSGIScriptAlias / /path/to/osqa-site/osqa.wsgi

    #this will force admin interface to work only
    #through https (optional)
    #"nimda" is the secret spelling of "admin" ;)
    <Location "/nimda">
        RewriteEngine on
        RewriteRule /nimda(.*)$ https://example.com/nimda$1 [L,R=301]
    </Location>
    CustomLog /var/log/httpd/OSQA/access_log common
    ErrorLog /var/log/httpd/OSQA/error_log
</VirtualHost>
#(optional) run admin interface under https
<VirtualHost ..your ip..:443>
    ServerAdmin forum@example.com
    DocumentRoot /path/to/osqa-site
    ServerName example.com
    SSLEngine on
    SSLCertificateFile /path/to/ssl-certificate/server.crt
    SSLCertificateKeyFile /path/to/ssl-certificate/server.key
    WSGIScriptAlias / /path/to/osqa-site/osqa.wsgi
    CustomLog /var/log/httpd/OSQA/access_log common
    ErrorLog /var/log/httpd/OSQA/error_log
    DirectoryIndex index.html
</VirtualHost>
-------------

5. Email subscriptions

   edit paths in the file cron/send_email_alerts
   set up a cron job to call cron/send_email_alerts once or twice a day
   subscription sender may be tested manually in shell
   by calling cron/send_email_alerts


C. CONFIGURATION PARAMETERS

Most stuff can be configured through the admin interface,
but there are some important settings that need to live in the settings files:

#all forum parameters are set in file settings_local.py
DEBUG=False #set to True to enable debug mode
LOG_FILENAME = 'osqa.log' #where logging messages should go
DATABASE_NAME = 'osqa'    # Or path to database file if using sqlite3.
DATABASE_USER = ''          # Not used with sqlite3.
DATABASE_PASSWORD = ''      # Not used with sqlite3.
DATABASE_ENGINE = 'mysql'   #mysql, etc
SERVER_EMAIL = ''
DEFAULT_FROM_EMAIL = ''
EMAIL_HOST_USER = ''
EMAIL_HOST_PASSWORD = ''    #not necessary if mailserver is run on local machine
EMAIL_SUBJECT_PREFIX = '[OSQA] '
EMAIL_HOST='osqa.com'
EMAIL_PORT='25'
EMAIL_USE_TLS=False
TIME_ZONE = 'America/Tijuana'

#if you set FORUM_SCRIPT_ALIAS= 'forum/'
#then OSQA will run at url http://example.com/forum
#FORUM_SCRIPT_ALIAS cannot have leading slash, otherwise it can be set to anything
FORUM_SCRIPT_ALIAS = '' #no leading slash, default = '' empty string

LANGUAGE_CODE = 'en' #forum language (see language instructions on the wiki)
EMAIL_VALIDATION = 'off' #string - on|off
MIN_USERNAME_LENGTH = 1
EMAIL_UNIQUE = False    #if True, email addresses must be unique in all accounts
APP_URL = 'http://osqa.com' #used by email notif system and RSS
WIKI_ON = True  #if False - community wiki feature is disabled

FEEDBACK_SITE_URL = None #None or url
LOGIN_URL = '/%s%s%s' % (FORUM_SCRIPT_ALIAS,'account/','signin/')

DJANGO_VERSION = 1.1 #must be either 1.0 or 1.1
RESOURCE_REVISION=4 #increment when you update media files - clients will be forced to load new version

D. Customization

Other than settings_local.py the following will most likely need customization:
* locale/*/django.po - language files that may also contain your site-specific messages
  if you want to start with english messages file - look for words like "forum" and
  "OSQA" in the msgstr lines
* templates/header.html and templates/footer.html may contain extra links
* templates/faq.html - put answers to users frequent questions
* templates/content/style/style.css - modify style sheet to add disctinctive look to your forum