osqa/INSTALL

   1 CONTENTS
   2 ------------------
   3 A. PREREQUISITES
   4 B. INSTALLATION
   5    1. Settings file
   6    2. Database
   7    3. Running OSQA in the development server
   8    4. Installation under Apache/WSGI
   9    5. Email subscriptions
  10 C. CONFIGURATION PARAMETERS (settings_local.py)
  11 D. CUSTOMIZATION
  12
  13
  14 A. PREREQUISITES
  15 -----------------------------------------------
  16 0. We recommend you to use python-setuptools to install pre-requirement libraries.
  17 If you haven't installed it, please try to install it first.
  18 e.g, sudo apt-get install python-setuptools
  19
  20 1. Python2.5/2.6, a rdbm (such as MySql or PostgreSql), Django v1.0/1.1
  21 Note: email subscription sender job requires Django 1.1, everything else works with 1.0
  22 Make sure you have the necessary support for python to communicate with your rdbm.
  23 sudo easy_install mysql-python (for MySql)
  24 sudo easy_install postgresql_psycopg2 (for PostgreSql)
  25
  26 2. html5lib
  27 http://code.google.com/p/html5lib/
  28 Used for HTML sanitizer
  29 sudo easy_install html5lib
  30
  31 3. Markdown2
  32 http://code.google.com/p/python-markdown2/
  33 sudo easy_install markdown2
  34
  35 4. Optional, but highly recommended, you may want to install south from http://south.aeracode.org/ , it will make upgrades a lot easier.
  36
  37
  38 5. Also optionally you may want to install Django Debug Toolbar for debugging.
  39 This is not required and OSQA will just ignore it if you don't have it.
  40 http://github.com/robhudson/django-debug-toolbar/tree/master
  41
  42 6. Depending on which modules you decide to enable (see bellow for more info on modules),
  43 you may need to install some aditional dependencies. Here's a list of the dependencies of each bundled module if any:
  44
  45     a) openidauth, depends on Python-openid
  46        http://openidenabled.com/python-openid/
  47
  48     b) sphinxfulltext, depends on djangosphinx, and obviously you'll have to install the sphinx search engine
  49        http://sphinxsearch.com/downloads.html
  50        http://github.com/dcramer/django-sphinx/tree/master/djangosphinx
  51
  52
  53
  54 B. INSTALLATION
  55 -----------------------------------------------
  56 0. Make sure you have all above python libraries installed.
  57
  58    make osqa installation server-readable on Linux command might be:
  59    chown -R yourlogin:apache /path/to/OSQA
  60
  61    directories templates/upfiles and log must be server writable
  62
  63    on Linux type chmod
  64    chmod -R g+w /path/to/OSQA/upfiles
  65    chmod -R g+w /path/to/log
  66
  67    above it is assumed that webserver runs under group named "apache"
  68
  69 1. Settings file
  70
  71 Copy settings_local.py.dist to settings_local.py and
  72 update all your settings. Check settings.py and update
  73 it as well if necessory.
  74 Section C explains configuration paramaters.
  75
  76 1b. Modules
  77
  78 Decide which modules you want to DISABLE. Each module adds a specific piece of functionality to OSQA, and
  79 by default, all are enabled, you have to disable the ones you want. If any module doesn't meet the required dependencies it just
  80 won't load.
  81 Currently bundled modules are:
  82
  83     localauth - provides local authentication and registration on your site, disable this if you want only external login
  84                 through any external provider
  85
  86     openidauth - adds support for open id on osqa and adds some openid providers to the signin page
  87
  88     oauthauth - adds support for oauth authentication on osqa and adds twitter as a signin provider on the signin page
  89
  90     facebookauth - adds facebook as an authentication provider
  91
  92     pgfulltext - adds support to full text search functionality through postgresql if you're useing it as your rdbm
  93
  94     sphinxfulltext - adds support for full text search with the sphinx search engine
  95                      (detailed instructions are in the module root folder)
  96
  97     robotstxt - adds a robots file editable throug the admin interface
  98
  99     recaptcha - adds support for recaptcha in the registration form
 100
 101     default_badges - the default set of badges, others can be added or used instead
 102
 103     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
 104
 105
 106 2. Database
 107
 108 Prepare your database by using the same database/account
 109 configuration from above.
 110 e.g,
 111 create database osqa DEFAULT CHARACTER SET UTF8 COLLATE utf8_general_ci;
 112 grant all on osqa.* to 'osqa'@'localhost';
 113 And then run "python manage.py syncdb" to synchronize your database.
 114
 115 If you're using south, then run "python manage.py migrate forum 0001 --fake".
 116
 117 When you're prompted to create a new superuser, answer "no". Once you get your site running, create a new user through the normal
 118 OSQA account creation process and that will be your super user.
 119
 120 3. Running OSQA on the development server
 121
 122 Run "python manage.py runserver" to startup django
 123 development environment.
 124 (Under Linux you can use command "python manage.py runserver `hostname -i`:8000",
 125 where you can use any other available number for the port)
 126
 127 4. Installation under Apache/WSGI
 128
 129 4.1 Prepare wsgi script
 130
 131 Make a file readable by your webserver with the following content:
 132
 133 ---------
 134 import os
 135 import sys
 136
 137 sys.path.insert(0,'/one/level/above') #insert to make sure that forum will be found
 138 sys.path.append('/one/level/above/OSQA') #maybe this is not necessary
 139 os.environ['DJANGO_SETTINGS_MODULE'] = 'OSQA.settings'
 140 import django.core.handlers.wsgi
 141 application = django.core.handlers.wsgi.WSGIHandler()
 142 -----------
 143
 144 insert method is used for path because if the forum directory name
 145 is by accident the same as some other python module
 146 you wull see strange errors - forum won't be found even though
 147 it's in the python path. for example using name "test" is
 148 not a good idea - as there is a module with such name
 149
 150
 151 4.2 Configure webserver
 152 Settings below are not perfect but may be a good starting point
 153
 154 ---------
 155 WSGISocketPrefix /path/to/socket/sock #must be readable and writable by apache
 156 WSGIPythonHome /usr/local #must be readable by apache
 157 WSGIPythonEggs /var/python/eggs #must be readable and writable by apache
 158
 159 #NOTE: all urs below will need to be adjusted if
 160 #settings.FORUM_SCRIPT_ALIAS !='' (e.g. = 'forum/')
 161 #this allows "rooting" forum at http://example.com/forum, if you like
 162 <VirtualHost ...your ip...:80>
 163     ServerAdmin forum@example.com
 164     DocumentRoot /path/to/osqa-site
 165     ServerName example.com
 166
 167     #run mod_wsgi process for django in daemon mode
 168     #this allows avoiding confused timezone settings when
 169     #another application runs in the same virtual host
 170     WSGIDaemonProcess OSQA
 171     WSGIProcessGroup OSQA
 172
 173     #force all content to be served as static files
 174     #otherwise django will be crunching images through itself wasting time
 175     Alias /m/ /path/to/osqa-site/forum/skins/
 176     Alias /upfiles/ /path/to/osqa-site/forum/upfiles/
 177     <Directory /path/to/osqa-site/forum/skins>
 178         Order deny,allow
 179         Allow from all
 180     </Directory>
 181
 182     #this is your wsgi script described in the prev section
 183     WSGIScriptAlias / /path/to/osqa-site/osqa.wsgi
 184
 185     #this will force admin interface to work only
 186     #through https (optional)
 187     #"nimda" is the secret spelling of "admin" ;)
 188     <Location "/nimda">
 189         RewriteEngine on
 190         RewriteRule /nimda(.*)$ https://example.com/nimda$1 [L,R=301]
 191     </Location>
 192     CustomLog /var/log/httpd/OSQA/access_log common
 193     ErrorLog /var/log/httpd/OSQA/error_log
 194 </VirtualHost>
 195 #(optional) run admin interface under https
 196 <VirtualHost ..your ip..:443>
 197     ServerAdmin forum@example.com
 198     DocumentRoot /path/to/osqa-site
 199     ServerName example.com
 200     SSLEngine on
 201     SSLCertificateFile /path/to/ssl-certificate/server.crt
 202     SSLCertificateKeyFile /path/to/ssl-certificate/server.key
 203     WSGIScriptAlias / /path/to/osqa-site/osqa.wsgi
 204     CustomLog /var/log/httpd/OSQA/access_log common
 205     ErrorLog /var/log/httpd/OSQA/error_log
 206     DirectoryIndex index.html
 207 </VirtualHost>
 208 -------------
 209
 210 5. Email subscriptions
 211
 212    edit paths in the file cron/send_email_alerts
 213    set up a cron job to call cron/send_email_alerts once or twice a day
 214    subscription sender may be tested manually in shell
 215    by calling cron/send_email_alerts
 216
 217
 218 C. CONFIGURATION PARAMETERS
 219
 220 Most stuff can be configured through the admin interface,
 221 but there are some important settings that need to live in the settings files:
 222
 223 #all forum parameters are set in file settings_local.py
 224 DEBUG=False #set to True to enable debug mode
 225 LOG_FILENAME = 'osqa.log' #where logging messages should go
 226 DATABASE_NAME = 'osqa'    # Or path to database file if using sqlite3.
 227 DATABASE_USER = ''          # Not used with sqlite3.
 228 DATABASE_PASSWORD = ''      # Not used with sqlite3.
 229 DATABASE_ENGINE = 'mysql'   #mysql, etc
 230 SERVER_EMAIL = ''
 231 DEFAULT_FROM_EMAIL = ''
 232 EMAIL_HOST_USER = ''
 233 EMAIL_HOST_PASSWORD = ''    #not necessary if mailserver is run on local machine
 234 EMAIL_SUBJECT_PREFIX = '[OSQA] '
 235 EMAIL_HOST='osqa.com'
 236 EMAIL_PORT='25'
 237 EMAIL_USE_TLS=False
 238 TIME_ZONE = 'America/Tijuana'
 239
 240 #if you set FORUM_SCRIPT_ALIAS= 'forum/'
 241 #then OSQA will run at url http://example.com/forum
 242 #FORUM_SCRIPT_ALIAS cannot have leading slash, otherwise it can be set to anything
 243 FORUM_SCRIPT_ALIAS = '' #no leading slash, default = '' empty string
 244
 245 LANGUAGE_CODE = 'en' #forum language (see language instructions on the wiki)
 246 EMAIL_VALIDATION = 'off' #string - on|off
 247 MIN_USERNAME_LENGTH = 1
 248 EMAIL_UNIQUE = False    #if True, email addresses must be unique in all accounts
 249 APP_URL = 'http://osqa.com' #used by email notif system and RSS
 250 WIKI_ON = True  #if False - community wiki feature is disabled
 251
 252 FEEDBACK_SITE_URL = None #None or url
 253 LOGIN_URL = '/%s%s%s' % (FORUM_SCRIPT_ALIAS,'account/','signin/')
 254
 255 DJANGO_VERSION = 1.1 #must be either 1.0 or 1.1
 256 RESOURCE_REVISION=4 #increment when you update media files - clients will be forced to load new version
 257
 258 D. Customization
 259
 260 Other than settings_local.py the following will most likely need customization:
 261 * locale/*/django.po - language files that may also contain your site-specific messages
 262   if you want to start with english messages file - look for words like "forum" and
 263   "OSQA" in the msgstr lines
 264 * templates/header.html and templates/footer.html may contain extra links
 265 * templates/faq.html - put answers to users frequent questions
 266 * templates/content/style/style.css - modify style sheet to add disctinctive look to your forum