8 files changed, 915 insertions, 0 deletions
diff --git a/forum/documentation/HOW_TO_DEBUG b/forum/documentation/HOW_TO_DEBUG
new file mode 100644
index 00000000..ba36198a
--- /dev/null
+++ b/forum/documentation/HOW_TO_DEBUG
@@ -0,0 +1,39 @@
+1) LOGGING
+Please remember that log files may contain plaintext passwords, etc.
+
+Please do not add print statements - at least do not commit them to git
+because in some environments printing to stdout causes errors
+
+Instead use python logging this way:
+--------------------------------
+#somewere on top of file
+import logging
+
+#anywhere below
+logging.debug('this maybe works')
+logging.error('have big error!')
+#or even
+logging.debug('') #this will add time, line number, function and file record 
+#sometimes useful record for call tracing on its own
+#etc - take a look at http://docs.python.org/library/logging.html
+-------------------------------
+
+in OSQA logging is currently set up in settings_local.py.dist
+please update it if you need - in older revs logging strings have less info
+
+messages of interest can be grepped out of the log file by module/file/function name
+e.g. to take out all django_authopenid logs run: 
+>grep 'osqa\/django_authopenid' log/django.osqa.log | sed 's/^.*MSG: //'
+in the example above 'sed' call truncates out a long prefix
+and makes output look more meaningful
+
+2) DJANGO DEBUG TOOLBAR
+osqa works with django debug toolbar
+if debugging under apache server, check 
+that debug toolbar media is loaded correctly
+if toolbar is enabled but you do not see it, possibly some Alias statement
+in apache config is wrong in your VirtualHost or elsewhere
+
+3) If you discover new debugging techniques, please add here.
+Possible areas to improve - at this point there is no SQL query logging,
+as well as request data and http header.
diff --git a/forum/documentation/INSTALL b/forum/documentation/INSTALL
new file mode 100644
index 00000000..c1a41544
--- /dev/null
+++ b/forum/documentation/INSTALL
@@ -0,0 +1,284 @@
+CONTENTS
+------------------
+A. PREREQUISITES
+B. INSTALLATION
+   1. Settings file
+   2. Database
+   3. Running Askbot in the development server
+   4. Installation under Apache/WSGI
+   5. Full text search
+   6. Email subscriptions
+   7. Sitemap
+   8. Miscellaneous
+C. CONFIGURATION PARAMETERS (settings_local.py)
+D. CUSTOMIZATION
+
+
+A. PREREQUISITES
+-----------------------------------------------
+Note: by default all installation activity is made in the superuser 'root' account.
+This can be achieved either by logging in as root (su root),
+or - if you have program sudo installed - prefix all commands with sudo.
+So sodo will be listed below as optional.
+
+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, Django v1.1.1
+
+1A If you are using MySQL, mysql client for python must be installed
+[sudo] easy_install mysql-python
+
+2. Python-openid v2.2
+http://openidenabled.com/python-openid/
+[sudo] easy_install python-openid
+
+4. html5lib
+http://code.google.com/p/html5lib/
+Used for HTML sanitizer
+[sudo] easy_install html5lib
+
+5. Markdown2
+http://code.google.com/p/python-markdown2/
+[sudo] easy_install markdown2
+
+6. Django Debug Toolbar
+http://github.com/robhudson/django-debug-toolbar/tree/master
+
+7. djangosphinx (optional - for full text questions+answer+tag)
+http://github.com/dcramer/django-sphinx/tree/master/djangosphinx
+
+8. sphinx search engine (optional, works together with djangosphinx)
+http://sphinxsearch.com/downloads.html
+
+9. recaptcha_django
+http://code.google.com/p/recaptcha-django/
+
+10. python recaptcha module
+http://code.google.com/p/recaptcha/
+Notice that you will need to register with recaptcha.net and receive
+recaptcha public and private keys that need to be saved in your
+settings_local.py file
+
+11. South
+http://south.aeracode.org/docs/installation.html
+Used for database schema and data migrations
+[sudo] easy_install South
+
+EXTRA DEPENDENCIES FOR PYTHON 2.4
+* hashlib (made standard in python 2.5)
+
+NOTES: django_authopenid is included into Askbot code
+and is significantly modified.  http://code.google.com/p/django-authopenid/
+no need to install this library
+
+B. INSTALLATION
+-----------------------------------------------
+0. Make sure you have all above python libraries installed.
+
+   DO NOT name the main directory 'askbot' - this name is reserved
+   for the future name of the app file itself.
+
+   make askbot installation server-readable on Linux command might be:
+   chown -R yourlogin:apache /path/to/askbot-site
+
+   directories: 
+    /path/to/askbot-site/forum/upfiles
+    /path/to/askbot-site/log
+   must be server writable
+
+   on Linux type chmod
+   chmod -R g+w /path/to/askbot-site/forum/upfiles
+   chmod -R g+w /path/to/askbot-site/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.
+
+Minimally required modification of settings_local.py are
+DATABASE_NAME
+DATABASE_USER
+DATABASE_PASSWORD
+DATABASE_ENGINE
+
+If you set these up, and your database is ready (see section 2),
+run (note that application 'forum' is under control of south migration system:
+
+python manage.py syncdb #create tables for anything not under control of migration system
+python manage.py migrate forum #run migration command - will apply all migrations in sequence
+
+Now you are ready to test your installation:
+python manage.py runserver `hostname -i`:8000
+(choose another port number if you wish)
+
+and askbot should be running - if you have any issues at this point (or later:)
+please post them at http://askbot.org/meta
+
+2. Database
+
+Prepare your database by using the same database/account
+configuration from above.
+
+If your host has database manager in the control panel - you 
+can use that or you can create database by typing commands manually
+
+on MySQL the commands are:
+
+create database askbot DEFAULT CHARACTER SET UTF8 COLLATE utf8_general_ci;
+grant all on askbot.* to 'askbot'@'localhost';
+
+And then run :
+
+python manage.py syncdb
+python manage.py migrate
+
+
+3. Running Askbot 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)
+
+you might want to have DEBUG=True in the beginning of settings.py
+when using the test server
+
+4. Installation under Apache/WSGI
+
+The main wsgi script is in the file django.wsgi
+it does not need to be modified
+
+4.1 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/askbot-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 askbot
+    WSGIProcessGroup askbot
+
+    #force all content to be served as static files
+    #otherwise django will be crunching images through itself wasting time
+    Alias /m/ /path/to/askbot-site/forum/skins/
+    Alias /upfiles/ /path/to/askbot-site/forum/upfiles/
+    <Directory /path/to/askbot-site/forum/skins>
+        Order deny,allow
+        Allow from all
+    </Directory>
+
+    #this is your wsgi script described in the prev section
+    WSGIScriptAlias / /path/to/askbot-site/django.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/askbot/access_log common
+    ErrorLog /var/log/httpd/askbot/error_log
+</VirtualHost>
+#(optional) run admin interface under https
+<VirtualHost ..your ip..:443>
+    ServerAdmin forum@example.com
+    DocumentRoot /path/to/askbot-site
+    ServerName example.com
+    SSLEngine on
+    SSLCertificateFile /path/to/ssl-certificate/server.crt
+    SSLCertificateKeyFile /path/to/ssl-certificate/server.key
+    WSGIScriptAlias / /path/to/askbot-site/django.wsgi
+    CustomLog /var/log/httpd/askbot/access_log common
+    ErrorLog /var/log/httpd/askbot/error_log
+    DirectoryIndex index.html
+</VirtualHost>
+-------------
+
+5. Full text search (using sphinx search)
+
+   Currently full text search works only with sphinx search engine
+   And builtin PostgreSQL (postgres only >= 8.3???)
+
+   5.1 Instructions for Sphinx search setup
+   Sphinx at this time supports only MySQL and PostgreSQL databases
+   to enable this, install sphinx search engine and djangosphinx
+
+   configure sphinx, sample configuration can be found in
+   sphinx/sphinx.conf file usually goes somewhere in /etc tree
+
+   build askbot index first time manually
+
+   % indexer --config /path/to/sphinx.conf --index askbot
+
+   setup cron job to rebuild index periodically with command
+   your crontab entry may be something like
+
+   0 9,15,21 * * * /usr/local/bin/indexer --config /etc/sphinx/sphinx.conf --all --rotate >/dev/null 2>&1
+   adjust it as necessary this one will reindex three times a day at 9am 3pm and 9pm
+
+   if your forum grows very big ( good luck with that :) you'll
+   need to two search indices one diff index and one main
+   please refer to online sphinx search documentation for the information
+   on the subject http://sphinxsearch.com/docs/
+
+   in settings_local.py set
+   USE_SPHINX_SEARCH=True
+   adjust other settings that have SPHINX_* prefix accordingly
+   remember that there must be trailing comma in parentheses for
+   SHPINX_SEARCH_INDICES tuple - particlarly with just one item!
+
+   in settings.py look for INSTALLED_APPS
+   and uncomment #'djangosphinx',
+
+
+6. Email subscriptions
+
+   This function at the moment requires Django 1.1
+
+   edit paths in the file forum/cron/send_email_alerts
+   set up a cron job to call forum/cron/send_email_alerts once or twice a day
+   subscription sender may be tested manually in shell
+   by calling foru/cron/send_email_alerts
+
+7. Sitemap
+Sitemap will be available at /<settings_local.FORUM_SCRIPT_ALIAS>sitemap.xml
+e.g yoursite.com/forum/sitemap.xml
+
+google will be pinged each time question, answer or
+comment is saved or a question deleted
+
+for this to be useful - do register you sitemap with Google at
+https://www.google.com/webmasters/tools/
+
+8. Miscellaneous
+
+There are some demo scripts under foru/sql_scripts folder,
+including badges and test accounts for CNProg.com. You
+don't need them to run your sample.
+
+C. 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
+  "Askbot" in the msgstr lines
+* skins
diff --git a/forum/documentation/INSTALL.pip b/forum/documentation/INSTALL.pip
new file mode 100644
index 00000000..92b1c7fa
--- /dev/null
+++ b/forum/documentation/INSTALL.pip
@@ -0,0 +1,31 @@
+* Install virtualenv and pip:
+    easy_install virtualenv
+    easy_install pip
+
+* Install MySQL:
+    sudo apt-get install mysql-client mysql-server
+
+* Install sphinxsearch. See:
+    [optional]
+    http://sphinxsearch.com/downloads.html
+    http://www.hackido.com/2009/01/install-sphinx-search-on-ubuntu.html
+    git://github.com/johnl/deb-sphinx-search.git
+
+* Install a virtual environment OUTSIDE of this directory:
+    pip install -E ~/env -r osqa-requirements.txt 
+[there is discussion on the pinax forums about what it should be outside
+the source directory]
+
+* Notice that you will need to register with recaptcha.net and receive
+    recaptcha public and private keys that need to be saved in your
+    settings_local.py file
+
+* Start your environment:
+    source ~/env/bin/activate
+
+* Install mysql-python into your virtualenv, because we can't
+automagically install it with pip:
+    easy_install --prefix ~/env/ mysql-python
+
+For more information about why pip can't automatically install the
+MySQL driver, see this message: http://groups.google.com/group/python-virtualenv/msg/ea988085951c92b3
diff --git a/forum/documentation/INSTALL.webfaction b/forum/documentation/INSTALL.webfaction
new file mode 100644
index 00000000..401971a0
--- /dev/null
+++ b/forum/documentation/INSTALL.webfaction
@@ -0,0 +1,346 @@
+Detailed instructions for installing OSQA on WebFaction
+
+Adapted from http://code.pinaxproject.com/wiki/DetailedPinaxWebfaction/
+
+Please email turian at gmail with any updates or corrections.
+
+
+Installing OSQA on Webfaction
+------------------------------------
+
+Details the steps for setting up OSQA on a Webfaction shared-hosting
+account, including email setup, using Apache2, mod_wsgi, psycopg2.
+
+If you want to search-and-replace through this file, you will need to replace:
+    osqa_server         [name of Webfaction application, which will be in ~/webapps/]
+    osqa_static         [name of Webfaction application for static media serving]
+    DOMAIN.com          [domain name for OSQA site]
+    PORT                [port number assigned by WebFaction to your mod_wsgi application]
+    SITENAME            [name you give the OSQA site, which will contain the apache logs]
+    MYOSQA              [name of the OSQA project]
+    MAILBOX_USERNAME    [username you give the email address]
+    MAILBOX_PASSWORD    [password that webfaction gives to this email username]
+    OSQADATABASE_NAME   [username you give the database]
+    OSQADATABASE_PASSWORD   [password that webfaction gives to this database]
+    ~/envs/osqa         [directory for the OSQA python environment, grep for 'env']
+    USERNAME            [your WebFaction username]
+
+Some things I'm not sure about:
+
+Here's what I don't know how to do:
+    * Set up a nginx server for static media.
+    * Configure sphinx search
+    * Use PostgreSQL, not MySQL: http://osqa.net/question/13/can-i-use-osqa-with-postgresql
+
+
+Webfaction Control Panel
+--------------------------
+
+(Note: if you sign up and pick django it will create the application
+for you, website/subdomain and associate the two for you.)
+
+    If necessary, add or create any domains or subdomains you may need.
+
+        https://panel.webfaction.com/domain/list/
+
+    Let's call the domain DOMAIN.com.
+
+    Create a new Webfaction application with a "Type:" of "mod_wsgi
+    2.5/Python2.5", naming it "osqa_server". (These instructions
+    might also work with mod_wsgi 2.0, if you like.)
+
+        https://panel.webfaction.com/app_/list
+
+    Note the port number assigned to the mod_wsgi application. Call
+    it PORT.
+
+    Create a new Webfaction website which will associate the subdomain
+    with the new osqa_server application. Give it name SITENAME, at least one
+    domain, and set it to use the osqa_server application for the site's
+    root location, "/".
+
+        https://panel.webfaction.com/site/list
+
+    You will need to create a database, typically one for each project
+    you create. Change the type to PostgreSql 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 may wish to change
+    the password.
+
+        https://panel.webfaction.com/database/create
+
+    Call these OSQADATABASE_NAME and OSQADATABASE_PASSWORD.
+
+    Save the database password for later.
+
+    [The following I haven't figured out yet]
+    You will probably want to add a static media server. This is a
+    Webfaction application. I created one of type "Static only (no
+    .htaccess)" and with the name of "osqa_static".
+
+        https://panel.webfaction.com/app_/create
+
+    To configure email, you need an email mailbox. Add one here. Note
+    that your mailbox password shouldn't be the same password you use
+    to SSH to webfaction.
+
+        https://panel.webfaction.com/mailbox/list
+
+    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
+
+
+OSQA Software
+--------------
+
+    Log onto webfaction and get the code. I use my fork because I have
+    a simple pip installation:
+        git://github.com/turian/osqa.git
+    In my situation, I keep source code in ~/utils/src, create
+    virtual environments in ~/envs/osqa, and create Pinax projects in
+    ~/webapps/osqa_server/projects.
+
+    You will need pip + virtualenv installed:
+
+        easy_install --prefix=~/utils/ pip
+        easy_install --prefix=~/utils/ virtualenv
+
+        cd ~/utils/src/
+        git clone git://github.com/turian/osqa.git
+        cd osqa
+
+        # We need python2.5 to be compatible with WSGI
+        python2.5 ~/utils/bin/pip install -E ~/envs/osqa -r osqa-requirements.txt 
+        source ~/envs/osqa/bin/activate
+
+        # [Optional] If you want a MySQL database
+        easy_install-2.5 --prefix ~/envs/osqa/ mysql-python
+
+Additional Software
+-------------------
+
+    [Note that PostgreSQL installation doesn't work for me.]
+
+    You will need to install psycopg2 separately for PostgreSQL.
+    Psycopg2 requires a little fiddling. Continuing to
+    work in the ~/utils/src/ directory:
+
+        cd ~/utils/src/
+        wget http://initd.org/pub/software/psycopg/psycopg2-2.0.13.tar.gz
+        tar zxf psycopg2-2.0.13.tar.gz
+        cd psycopg2-2.0.13
+        nano setup.cfg
+
+        # edit the line reading "#pg_config=" so that it reads:
+            "pg_config=/usr/local/pgsql/bin/pg_config"
+
+        python2.5 setup.py build
+        python2.5 setup.py install
+
+
+Create a Project
+----------------
+
+    In Pinax, you clone a project from OSQA.
+    However, OSQA we just copy it.
+
+        cd ~/webapps/osqa_server
+        mkdir projects
+        cd projects
+        cp -R ~/utils/src/osqa MYOSQA
+        cd MYOSQA
+        export OSQAPROJECT=`pwd`
+
+    Make some directories, as described in the OSQA INSTALL file:
+    [okay I haven't actually done this yet]
+
+#        mkdir -p $OSQASITE/upfiles/
+#        mkdir -p $OSQALOG
+#        sudo chown -R `whoami`:www-data $OSQASITE
+#        sudo chown -R `whoami`:www-data $OSQALOG
+#        chmod -R g+w $OSQASITE/upfiles
+#        chmod -R g+w $OSQALOG
+
+
+    Edit the settings files:
+
+        cd $OSQAPROJECT
+        cp settings_local.py.dist settings_local.py
+        vi settings_local.py settings.py 
+
+        Pay attention to the following settings:
+
+            DATABASE_ENGINE = 'mysql'
+            DATABASE_NAME = 'OSQADATABASE_NAME'
+            DATABASE_USER = 'OSQADATABASE_NAME'
+            DATABASE_PASSWORD = 'OSQADATABASE_PASSWORD'
+
+            EMAIL_HOST='smtp.webfaction.com'
+            EMAIL_HOST_USER='MAILBOX_USERNAME'
+            EMAIL_HOST_PASSWORD='MAILBOX_PASSWORD'
+            EMAIL_PORT='25'
+            DEFAULT_FROM_EMAIL = 'MAILBOX_USERNAME@DOMAIN.com'
+            SERVER_EMAIL = 'MAILBOX_USERNAME@DOMAIN.com'
+            # The following setting might not be necessary, it's used in Pinax tho
+            CONTACT_EMAIL = "MAILBOX_USERNAME@DOMAIN.com"
+
+            APP_URL = 'http://DOMAIN.com' #used by email notif system and RSS
+
+        [Later on, the install instructions should talk about]
+            SERVE_MEDIA = False     # [Not present, not ready yet]
+
+    Create a directory for logs:
+
+        cd $OSQAPROJECT
+        mkdir log
+
+    Modify mail cron scripts "cron/send_email_alerts" as follows:
+    [Pinax has cron/emit_notices.sh, cron/retry_deferred.sh,
+    cron/send_mail.sh, are these also necessary?]
+
+            #!/bin/sh
+
+            WORKON_HOME=~/envs/osqa
+            PROJECT_ROOT=~/webapps/osqa_server/projects/MYOSQA/
+
+            # activate virtual environment
+            . $WORKON_HOME/bin/activate
+
+            cd $PROJECT_ROOT
+            python manage.py send_email_alerts >> $PROJECT_ROOT/log/cron_mail.log 2>&1
+
+        Use command "crontab -e" to add this script to your cron file, to run twice a day::
+
+            1 0,12 * * * ~/webapps/osqa_server/projects/MYOSQA/cron/send_email_alerts
+
+    [Configure sphinx]
+
+    Create the database tables, indices, and so forth:
+
+        python manage.py syncdb
+
+    [Ignore the following static media steps, I haven't tried them]
+    Build media directory links within the project and create symbolic
+    links on the static media server.
+        python manage.py build_media -all
+        mkdir ~/webapps/OSQA_STATIC/MYOSQA
+        ln -sd ~/webapps/osqa_server/projects/MYOSQA/site_media ~/webapps/OSQA_STATIC/MYOSQA/site_media
+
+
+    Set up the badges:
+
+        1. You should run the SQL commands in:
+
+                 sql_scripts/badges.sql
+
+        2. Edit paths in the file `cron/multi_award_badges`. (This
+        file doesn't yet exist in the git repositories, so just
+        copy `cron/send_email_alerts` and make sure the command
+        `multi_award_badges` is executed.)
+
+        3. Run `cron/multi_award_badges` to make sure it works okay.
+
+        4. Use `crontab -e` to call `cron/multi_award_badges` maybe
+        four times an hour.
+
+            4,19,34,49 * * * * ~/webapps/osqa_server/projects/MYOSQA/cron/multi_award_badges
+
+        5. Repeat steps 1-4 for `cron/once_award_badges`.
+
+
+Configure Apache2
+----------------
+
+    Edit  ~/webapps/osqa_server/apache2/conf/httpd.conf as follows::
+
+        ServerAdmin "MAILBOX_USERNAME@DOMAIN.com"
+        ServerRoot "/home/USERNAME/webapps/osqa_server/apache2"
+        ServerName DOMAIN.com
+
+        LoadModule dir_module modules/mod_dir.so
+        LoadModule env_module modules/mod_env.so
+        #LoadModule setenvif_module modules/mod_setenvif.so
+        LoadModule log_config_module modules/mod_log_config.so
+        LoadModule mime_module modules/mod_mime.so
+        LoadModule rewrite_module modules/mod_rewrite.so
+        LoadModule wsgi_module modules/mod_wsgi.so
+
+        KeepAlive Off
+        Listen PORT
+        LogFormat "%{X-Forwarded-For}i %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
+        CustomLog /home/USERNAME/logs/user/access_osqa_server_log combined
+        ErrorLog /home/USERNAME/logs/user/error_osqa_server_log
+        ServerLimit 2
+
+        #SetEnvIf X-Forwarded-SSL on HTTPS=1
+
+        WSGIPythonPath /home/USERNAME/envs/osqa/lib/python2.5/site-packages/
+        WSGIScriptAlias / /home/USERNAME/webapps/osqa_server/projects/MYOSQA/osqa.wsgi
+
+        LoadModule alias_module modules/mod_alias.so
+        WSGIDaemonProcess osqaWSGI user=USERNAME group=USERNAME threads=25 python-path=/home/USERNAME/envs/osqa/lib/python2.5/site-packages
+        WSGIProcessGroup osqaWSGI
+
+        NameVirtualHost 127.0.0.1:PORT
+
+        #ErrorLog "logs/MYOSQA_2009_05_06.log"
+        SetHandler none
+        #Alias /site_media /home/USERNAME/webapps/static/MYOSQA/site_media
+
+        #force all content to be served as static files
+        #otherwise django will be crunching images through itself wasting time
+        Alias /content/ /home/USERNAME/webapps/osqa_server/projects/MYOSQA/templates/content/
+        Alias /forum/admin/media/ /home/turian/envs/osqa/lib/python2.5/site-packages/django/contrib/admin/media/
+        #AliasMatch /([^/]*\.css) /home/USERNAME/webapps/osqa_server/projects/MYOSQA/templates/content/style/$1
+        <Directory "/home/USERNAME/webapps/osqa_server/projects/MYOSQA/templates/content">
+        #    Order deny,allow
+        #    Allow from all
+        </Directory>
+
+    If you want virtual hosts of the admin interface under HTTPS, please
+    look at OSQA's install file.
+
+    Create osqa.wsgi and edit it:
+        cp osqa.wsgi.dist osqa.wsgi
+
+    Edit  ~/webapps/osqa_server/projects/MYOSQA/deploy/osqa.wsgi as follows::
+        
+        import os
+        import sys
+        
+        # redirect sys.stdout to sys.stderr for bad libraries like geopy that uses
+        # print statements for optional import exceptions.
+        sys.stdout = sys.stderr
+        
+        from os.path import abspath, dirname, join
+        from site import addsitedir
+        
+        # add the virtual environment site-packages to the path
+        from site import addsitedir
+        addsitedir('/home/USERNAME/envs/osqa/lib/python2.5/site-packages')
+        
+        sys.path.insert(0, abspath(join(dirname(__file__), "../")))
+        sys.path.append(abspath(dirname(__file__)))
+        
+        from django.conf import settings
+        os.environ["DJANGO_SETTINGS_MODULE"] = "MYOSQA.settings"
+
+        #print sys.path
+
+        from django.core.handlers.wsgi import WSGIHandler
+        application = WSGIHandler()
+
+And then you're up and running with:
+
+    ~/webapps/osqa_server/apache2/bin/stop
+    ~/webapps/osqa_server/apache2/bin/start
+
+You should log in to the admin interface (http://DOMAIN.com/admin/),
+and go to "Sites > Sites", and change the domain name that is used in
+all emails.
diff --git a/forum/documentation/ROADMAP.rst b/forum/documentation/ROADMAP.rst
new file mode 100644
index 00000000..c79e0ae4
--- /dev/null
+++ b/forum/documentation/ROADMAP.rst
@@ -0,0 +1,88 @@
+Intro
+=========
+ROADMAP aims to streamline activities of the Askbot open source project and
+to minimize ad-hoc approaches of "big-picture" level.
+
+Aksbot is a Question and Asnwer system for the normal people!
+
+Let's discuss stuff that goes into this file on
+http://groups.google.com/group/askbot
+
+Bacic principles of the project
+==================================
+Here they are:
+
+* our rule #1 is that all developers have commit right to the project
+  repository, but they must follow this ROADMAP and TODO - 
+  to keep up with our own sanity.
+* we welcome contributions by other people and show tolerance
+  and patience - especially to the new team members.
+* when users who might not be tech-savvy ask questions -
+  we try to answer to the point and using their language 
+  (i.e. not programmer jargon:)
+* we favor plain and minimalistic style of programming, but pay
+  attention to detail - especially details of user experience.
+
+We try do develop using the following workflow:
+
+* specify problem that we try to solve
+* create requirements that will guarantee a solution, once met
+* dream up some implementation ideas (maybe even some sketches on the paper)
+* discuss and decide on the best one
+* write and test code
+
+The process doesn't have to be this formal all the time, but trying to stick
+to some subset of this almost always helps! 
+Especially it helps to iron out disagreements between
+individual programmers (which if you are one - you know are qute common
+- and they don't all end well :).
+
+Ad-hoc programming - i.e. simply go and add code - is not really encouraged.
+This works fine in the one person team or when the team consists of 
+best friends, but is almost sure to fail in a heterogenous group.
+
+Architecture and Requirements
+=====================================
+Obviously Django and Python are pre-made choices - so this
+is not going to change any time soon. At this point all of
+the client side Javascript is written using jQuery library.
+
+Our basic principle is that Askbot should be a mashable Q&A component.
+Askbot is an application written in Python/Django. So it should be 
+distributable as a Django App alone or as a whole site (by option).
+
+If we develop sub-systems that can be used in the broader scope - 
+we package that thing as a separate django application (login system is one example).
+
+We will start using Google Closure library soon!
+
+Sub-systems
+-----------------
+* authentication system
+* Q&A system
+* admin interface
+* full text search
+* skins (directory forum/skins)
+
+Authentication system
+-------------------------
+Authentication system will be a separate django application
+
+Here is the discussion thread:
+* http://groups.google.com/group/askbot/browse_thread/thread/1916dfcf666dd56c
+
+Most of the requirements are listed in the first message
+
+Skins
+-----------
+Skins eventually must be upgrade-stable - that is people who created custom
+skins should not need to change anything if something changes in the code
+
+Admin interface
+-----------------------
+* extend forum/settings.py to list default settings of various groups
+* create Registry database table the will store setting values
+* leave only essential settings that go to the main django settings.py
+Create key-value storage
+* should some settings be accessible to admins and some to staff???
+  for example-secret keys probably should not be shared with staff members
diff --git a/forum/documentation/TODO.rst b/forum/documentation/TODO.rst
new file mode 100644
index 00000000..f202a3f7
--- /dev/null
+++ b/forum/documentation/TODO.rst
@@ -0,0 +1,63 @@
+note: there is also WISH_LIST. Here is only stuff that will be done soon.
+
+Site looks
+===========
+* make links within posts blue so that they are visible
+
+Code Cleanups
+==============
+* remove usage of EXTERNAL_LEGACY_LOGIN
+* clean up forum_modules:
+  * keep this directory for dependency modules that can be shared
+    by multiple apps, 
+  * but move other things that are not shared
+    inside forum app directory
+  * one-by one convert "auto-discovery" modules into 
+    regular explicit python imports
+* python2.4 incompatibilities
+  *  datatime.datetime.strptime
+
+Bugs
+======
+* make sure that search feature covers questions and answers 
+  (title, body, tags)
+
+Refactoring
+=============
+* merge search, question and index view functions into one
+
+Skins
+=======
+* organize templates and document them so that
+  skins could be more easily created by others
+  who are savvy enough
+* identify and maybe create snippet-type templates
+  and put them into a separate directory 
+  for example:
+  * gravatar (currently a string in 
+    forum/templatetags/extra_tags.py - try inclusion template
+    and see if it slows things down a lot)
+  * question body
+  * answer body
+  * datetime widget???
+* there is a separator line between posts
+  but it shows either before the post or after
+  it is nice that separator is lightweight -
+  based on css alone - but we need to fix it so that
+  it shows only between the posts as a joining item
+
+Features
+===========
+* new login system, please see 
+  http://groups.google.com/group/askbot/browse_thread/thread/1916dfcf666dd56c
+  on a separate branch multi-auth-app, then merge
+* forum admin interface, some badge configuration
+
+Development environment
+==========================
+* set up environment for closure development
+
+Project website
+====================
+* Logo!!! Ideas?
+* Adopt Jekyll for project site and transition from Dango
diff --git a/forum/documentation/WISH_LIST b/forum/documentation/WISH_LIST
new file mode 100644
index 00000000..3e383d3e
--- /dev/null
+++ b/forum/documentation/WISH_LIST
@@ -0,0 +1,55 @@
+* smarter debug mode
+* The wonder bar (integrated the search / ask functionality)
+* The authentication system ???
+* allow multiple logins to the same account
+* allow multiple logins to the same account
+* more advanced templating/skinning system
+* per-tag email  subscriptions
+* view for personalized news on the site
+* a little flag popping when there are news
+* drill-down mode for navigation by tags
+* improved admin console
+* sort out mess with profile - currently we patch django User
+
+* Some functionality should be moved out of the forums app, in the case
+that the forum app is restricted only to authenticated users:
+    
+        (r'^%s/$' % _('signin/'), 'django_authopenid.views.signin'),
+        url(r'^%s$' % _('about/'), app.about, name='about'),
+        url(r'^%s$' % _('faq/'), app.faq, name='faq'),
+        url(r'^%s$' % _('privacy/'), app.privacy, name='privacy'),
+        url(r'^%s$' % _('logout/'), app.logout, name='logout'),
+        url(r'^%s$' % _('feedback/'), app.feedback, name='feedback'),
+        (r'^%sfb/' % _('account/'),  include('fbconnect.urls')),
+        (r'^%s' % _('account/'), include('django_authopenid.urls')),
+
+Copied from old todo list:
+
+There are two kinds of things that can be done:
+refactorings (think of jogging in the morning, going to a spa, well make the code better :)
+new features (go to law school, get a job, do something real)
+Just a joke - pick yourself a task and work on it.
+
+==Refactoring==
+* validate HTML
+* set up loading of default settings from inside the /forum dir
+* automatic dependency checking for modules
+* propose how to rename directory forum --> osqa
+  without breaking things and keeping name of the project root
+  named the same way - osqa
+
+==New features==
+Whoever wants - pick a feature from the WISH_LIST
+add it here and start working on it
+If you are not starting immediately - leave it on the wishlist :)
+
+==Notes==
+1)after this is done most new suggested features
+  may be worked on easily since most of them
+  only require editing view functions and templates
+
+  However, anyone can work on new features anyway - you'll
+  just have to probably copy-paste your code into 
+  the branch undergoing refactoring which involves 
+  splitting the files. Auto merging across split points
+  is harder or impossible.
diff --git a/forum/documentation/askbot-requirements.txt b/forum/documentation/askbot-requirements.txt
new file mode 100644
index 00000000..66a37fbe
--- /dev/null
+++ b/forum/documentation/askbot-requirements.txt
@@ -0,0 +1,9 @@
+django>=1.1         # Note: email subscription sender job requires Django 1.1, everything else works with 1.0
+#mysql-python       # Can't use with pip, see http://groups.google.com/group/python-virtualenv/msg/ea988085951c92b3
+python-openid
+html5lib
+markdown2
+git+git://github.com/robhudson/django-debug-toolbar.git
+git+git://github.com/dcramer/django-sphinx.git
+svn+http://recaptcha-django.googlecode.com/svn/trunk/
+svn+http://recaptcha.googlecode.com/svn/trunk/recaptcha-plugins/python/