adapted badges to the new schema

[osqa.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index f70b3ec7594e1680349306f427100e54e50890b8..f655e1d22ddab08a5fe46e500fbab2511e5f293b 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -6,10 +6,7 @@ B. INSTALLATION
    2. Database
    3. Running OSQA in the development server
    4. Installation under Apache/WSGI
    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
+   5. Email subscriptions

 C. CONFIGURATION PARAMETERS (settings_local.py)
 D. CUSTOMIZATION
 
 C. CONFIGURATION PARAMETERS (settings_local.py)
 D. CUSTOMIZATION
 


@@ -20,45 +17,39 @@ A. PREREQUISITES
 If you haven't installed it, please try to install it first.
 e.g, sudo apt-get install python-setuptools
 
 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
+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
 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
+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. Python-openid v2.2
-http://openidenabled.com/python-openid/
-sudo easy_install python-openid
-
-4. html5lib
+2. html5lib

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

-5. Markdown2
+3. Markdown2

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

-6. Django Debug Toolbar
+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
 
 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
+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:

 
 

-8. sphinx search engine (optional, works together with djangosphinx)
-http://sphinxsearch.com/downloads.html
+    a) openidauth, depends on Python-openid
+       http://openidenabled.com/python-openid/

 
 

-9. recaptcha_django
-http://code.google.com/p/recaptcha-django/
+    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

 
 

-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
 -----------------------------------------------
 
 B. INSTALLATION
 -----------------------------------------------


@@ -66,7 +57,7 @@ B. INSTALLATION
 
    make osqa installation server-readable on Linux command might be:
    chown -R yourlogin:apache /path/to/OSQA
 
    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
    directories templates/upfiles and log must be server writable
 
    on Linux type chmod


@@ -77,30 +68,62 @@ B. INSTALLATION
 
 1. Settings file
 
 
 1. Settings file
 

-Copy settings_local.py.dist to settings_local.py and 
-update all your settings. Check settings.py and update 
+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.
 
 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
 
 2. Database
 

-Prepare your database by using the same database/account 
+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.
 
 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 
+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 
+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)
 
 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
 4. Installation under Apache/WSGI
 
 4.1 Prepare wsgi script


@@ -118,7 +141,7 @@ import django.core.handlers.wsgi
 application = django.core.handlers.wsgi.WSGIHandler()
 -----------
 
 application = django.core.handlers.wsgi.WSGIHandler()
 -----------
 

-insert method is used for path because if the forum directory name 
+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
 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


@@ -133,7 +156,7 @@ 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
 
 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 
+#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>
 #settings.FORUM_SCRIPT_ALIAS !='' (e.g. = 'forum/')
 #this allows "rooting" forum at http://example.com/forum, if you like
 <VirtualHost ...your ip...:80>


@@ -144,8 +167,8 @@ WSGIPythonEggs /var/python/eggs #must be readable and writable by apache
     #run mod_wsgi process for django in daemon mode
     #this allows avoiding confused timezone settings when
     #another application runs in the same virtual host
     #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 
+    WSGIDaemonProcess OSQA
+    WSGIProcessGroup OSQA

 
     #force all content to be served as static files
     #otherwise django will be crunching images through itself wasting time
 
     #force all content to be served as static files
     #otherwise django will be crunching images through itself wasting time


@@ -184,75 +207,21 @@ WSGIPythonEggs /var/python/eggs #must be readable and writable by apache
 </VirtualHost>
 -------------
 
 </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 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
+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
 
    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 
+   subscription sender may be tested manually in shell

    by calling cron/send_email_alerts
 
    by calling 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 sql_scripts folder, 
-including badges and test accounts for CNProg.com. You 
-don't need them to run your sample.

 
 C. CONFIGURATION PARAMETERS
 
 
 C. CONFIGURATION PARAMETERS
 

-#the only parameter that needs to be touched in settings.py is 
-DEBUG=False #set to True to enable debug mode
+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
 
 #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.
 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.


@@ -267,11 +236,6 @@ EMAIL_HOST='osqa.com'
 EMAIL_PORT='25'
 EMAIL_USE_TLS=False
 TIME_ZONE = 'America/Tijuana'
 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'<p>Ask and answer questions, make the world better!</p>' #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
 
 #if you set FORUM_SCRIPT_ALIAS= 'forum/'
 #then OSQA will run at url http://example.com/forum


@@ -283,19 +247,8 @@ 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
 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
 
 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 = '<span class="orange">OSQA</span>'
-

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


@@ -309,6 +262,5 @@ Other than settings_local.py the following will most likely need customization:
   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
   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
 * templates/faq.html - put answers to users frequent questions
 * templates/content/style/style.css - modify style sheet to add disctinctive look to your forum