CONTENTS ------------------ A. PREREQUISITES B. INSTALLATION 1. Settings file 2. Database 3. Running OSQA 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 ----------------------------------------------- 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, MySQL, Django v1.0/1.1 Note: email subscription sender job requires Django 1.1, everything else works with 1.0 Make sure mysql for python provider has been 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 NOTES: django_authopenid is included into OSQA 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. 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. 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. 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) you might want to have DEBUG=True in the beginning of settings.py when using the test server 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 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/ Order deny,allow Allow from all #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" ;) RewriteEngine on RewriteRule /nimda(.*)$ https://example.com/nimda$1 [L,R=301] CustomLog /var/log/httpd/OSQA/access_log common ErrorLog /var/log/httpd/OSQA/error_log #(optional) run admin interface under https 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 ------------- 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 osqa index first time manually % indexer --config /path/to/sphinx.conf --index osqa 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 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 7. Sitemap Sitemap will be available at /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 sql_scripts folder, including badges and test accounts for CNProg.com. You don't need them to run your sample. C. CONFIGURATION PARAMETERS #the only parameter that needs to be touched in settings.py is DEBUG=False #set to True to enable debug mode #all forum parameters are set in file settings_local.py 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' APP_TITLE = u'OSQA Q&A Forum' #title of your forum APP_KEYWORDS = u'OSQA,forum,community' #keywords for search engines APP_DESCRIPTION = u'Ask and answer questions.' #site description for searche engines APP_INTRO = u'

Ask and answer questions, make the world better!

' #slogan that goes to front page in logged out mode APP_COPYRIGHT = '' #copyright message #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 GOOGLE_SITEMAP_CODE = '' #code for google site crawler (look up google webmaster tools) GOOGLE_ANALYTICS_KEY = '' #key to enable google analytics on this site BOOKS_ON = False #if True - books tab will be on WIKI_ON = True #if False - community wiki feature is disabled #experimental - allow password login through external site #must implement django_authopenid/external_login.py #included prototype external_login works with Mediawiki USE_EXTERNAL_LEGACY_LOGIN = True #if false OSQA uses it's own login/password EXTERNAL_LEGACY_LOGIN_HOST = 'login.osqa.com' EXTERNAL_LEGACY_LOGIN_PORT = 80 EXTERNAL_LEGACY_LOGIN_PROVIDER_NAME = 'OSQA' 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/about.html - a place to explain for is your forum for * templates/faq.html - put answers to users frequent questions * templates/content/style/style.css - modify style sheet to add disctinctive look to your forum