diff options
author | Evgeny Fadeev <evgeny.fadeev@gmail.com> | 2010-06-16 19:02:14 -0400 |
---|---|---|
committer | Evgeny Fadeev <evgeny.fadeev@gmail.com> | 2010-06-16 19:02:14 -0400 |
commit | b058dd3e57d273d3f3f10f306a6ef82c49d74ca4 (patch) | |
tree | e947213804b12a1d442abd7f7f16d5e8604e1c94 | |
parent | 1d0ba8c4136f1871bd50f618503bd51bc8a15ab3 (diff) | |
download | askbot-b058dd3e57d273d3f3f10f306a6ef82c49d74ca4.tar.gz askbot-b058dd3e57d273d3f3f10f306a6ef82c49d74ca4.tar.bz2 askbot-b058dd3e57d273d3f3f10f306a6ef82c49d74ca4.zip |
updated INSTALL doc
-rw-r--r-- | askbot/doc/INSTALL | 293 | ||||
-rw-r--r-- | askbot/doc/INSTALL.rst | 257 |
2 files changed, 257 insertions, 293 deletions
diff --git a/askbot/doc/INSTALL b/askbot/doc/INSTALL deleted file mode 100644 index 4589e1ba..00000000 --- a/askbot/doc/INSTALL +++ /dev/null @@ -1,293 +0,0 @@ -CONTENTS ------------------- -A. INSTALLATION -B. DEPLOYMENT - 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. INSTALLATION - -NOTE: if you need to install in non-standard locations -please take a look here: http://askbot.org/wiki/index.php/Installing_software_components_at_non-standard_locations - -type - -> python setup.py install - -or - -> easy_install askbot - -then, if you need to start a new deployment, type - -> startforum - -Please read a few paragraphs of the following section on -how to initialize the application - -ATTENTION WINDOWS USERS: you will need to manually install -binary for mysql-python from here -http://www.codegood.com/archives/4 - -B. DEPLOYMENT - -if you are adding askbot to your existing project that already -has other apps, you'll need to "merge" some of the files in -directory askbot/install_templates into your corresponding project files -more instuctions about this are to follow soon - if you have questions -ask on the forum - -for new deployment -> startforum - -and answer questions in the end you should be able to get almost -working installation, you'll need to edit file settings.py -and at least enter database name, user name and password - -then type - -> python manage.py syncdb -> python manage.py migrate forum - -now run: - -> python manage.py runserver `hostname -i`:8000 #or use some other port - -command `hostname -i` returns IP address on Unix, you can type the IP by hand too - - - - - - -NOTES BELOW ARE OUTDATED, but may be useful -if you have questions - please ask at http://askbot.org - - - - - - - -NOTE: If you want to upgrade software, not install from scratch - - take a look into forum/documentation/UPGRADE - ------------------------------------------------ -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 subsctiptions and badge awards - - copy file forum/cron/askbot_cron_job - somewhere in your user space (outside of forum) - edit paths in that file - - set up a cron job to call it say hourly - - the commands within askbot_cron_job can also be called manually - from the command line for the testing purposes - -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 forum/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/askbot/doc/INSTALL.rst b/askbot/doc/INSTALL.rst new file mode 100644 index 00000000..a49dd364 --- /dev/null +++ b/askbot/doc/INSTALL.rst @@ -0,0 +1,257 @@ +Askbot is a Question and Answer (Q&A) forum whose design is inspired by StackOverflow_ +and YahooAnswers_ and other similar projects (to lesser extent). + +Askbot is written in Python_ on top of Django_ platform. +Code of Askbot grew out of CNPROG_ project originally written by +`Mike Chen <http://cn.linkedin.com/in/mikegangchen>`_ and Sailing Cai. + +If you have any questions installing or tweaking askbot - please do not hesitate to ask +at the forum_ or email to admin@askbot.org. + +Prerequisites +====================== +To install and run Askbot the following are required: + +* Python_ version 2.4 - 2.6 (Version 3 is not supported) +* MySQL_ version 5 + +For the production deployment you will also need a webserver capable to run +python web applications (see section Deployment_). + +Installation Instructions +=========================== + +To simplify future deployment, please make sure to use the same python +interpreter for the installation and testing as the one assigned +(or will be assigned) to the webserver. + +If you already have `easy_install`_ on your system, then type:: + easy_install askbot + +If you are using the easy\_install tool, make sure that it was also +originally installed with the python interpreter mentioned above, +otherwise use the second method: + +Download the latest version of askbot_, unzip and untar the archive and run:: + python setup.py install + +If you are planning to use askbot on Windows, please install +`mysql-python windows binary package <http://www.codegood.com/archives/4>`_ manually. + +Chances are that steps above will complete your installation. If so, then +proceed to the Configuration_ section. Below are extra installation notes +that cover some special cases. + +To install in non-standard locations add parameter --prefix=/path/to/some/dir to both commands. + +Askbot depends on about a dozen other packages. Normally those dependencies will be +automatically resolved. However, if something does not go well - e.g. +some dependency package site is not accessible, please +download and install some of those things +( +django-1.1.2_, +django-debug-toolbar_, +South_, +recaptcha-client_, +markdown2_, +html5lib_, +python-openid_, +django-keyedcache_, +django-threaded-multihost_, +mysql-python_ +) manually. + +If any of the provided links +do not work please try to look up those packages or notify askbot maintainers at admin@askbot.org. + +.. _Configuration: +Configuration +==================== + +type:: + startforum + +and answer questions. + +The startforum script will attempt to create necessary directories +and copy files. + +If you are creating a new Django project, you will need to edit file + +In the case you are adding askbot to an existing Django project, you will need to +merge askbot files settings.py_ and urls.py_ into your project files manually. + +Within settings.py, at the very minimum you will need to provide correct values to:: + DATABASE_NAME = '' + DATABASE_USER = '' + DATABASE_PASSWORD = '' + +within single quotes - login credential to your mysql database. Assuming that +the database exists, you can now install the tables by running:: + python manage.py syncdb + python manage.py migrate forum + +now run the development sever:: + python manage.py runserver `hostname -i`:8000 #or use some other port number > 1024 + +`hostname -i` is a Unix command returning the IP address of your system, you can also type +the IP manually or replace it with localhost if you are installing askbot +on a local machine. + +Your basic installation is now complete. Many settings can be +changed at runtime by following url /settings. + +If you choose to host a real website, please read +section Deployment_. For advice on hosting Askbot, please take +a look at section Hosting_. + +.. _Deployment: +Deployment +============== +Webserver process must be able to write to the following locations:: + /path/to/django-project/log/ + /path/to/django-project/askbot/upfiles + +If you know user name or the group name under which the webserver runs, +you can make those directories writable by setting the permissons +accordingly: + +For example, if you are using Linux installation of apache webserver running under +group name 'apache' you could do the following:: + + chown -R yourlogin:apache /path/to/askbot-site + chmod -R g+w /path/to/askbot-site/forum/upfiles + chmod -R g+w /path/to/askbot-site/log + +If your account somehow limits you from running such commands - please consult your +system administrator. + +Installation under Apache/mod\_wsgi +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Apache/mod\_wsgi combination is the only type of deployment described in this +document at the moment. mod_wsgi_ is currently the most resource efficient +apache handler for the Python web applications. + +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> + +Database configuration +~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Database can be prepared via your hosting control panel, if available or +can be created manually (provided that you have a mysql account with +a sufficient privilege) + +The relevant MySQL the commands are:: + create database askbot DEFAULT CHARACTER SET UTF8 COLLATE utf8_general_ci; + grant all privileges on dbname.* to dbuser@localhost identified by 'dbpassword'; + +where dbname, dbuser and dbpassword should be replaced with the real values. +MySQL will create a user with those credentials if it does not yet exist. + +Automation of maintenance jobs +=============================== + +There are routine tasks that should be performed periodically +from the command line. They can be automated via cron_ jobs + +File askbot_cron_job_ has a sample script that can be run say hourly + +The script currently does two things: (1) sends delayed email alerts and +(2) awards badges. These two actions can be separated into two separate jobs, +if necessary + +Sitemap registration +======================= +Sitemap to your forum will be available at url /<settings.FORUM\_SCRIPT\_ALIAS>sitemap.xml +e.g yoursite.com/forum/sitemap.xml or yoursite.com/sitemap.xml + +Google will be pinged each time question, answer or +comment is saved or a question deleted. + +If you register you sitemap through `Google Webmasters Tools`_ Google +will have be indexing your site more efficiently. + +.. _`Google Webmasters Tools`: https://www.google.com/webmasters/tools/ +.. _Python: http://www.python.org/download/ +.. _MySQL: http://www.mysql.com/downloads/mysql/#downloads +.. _YahooAnswers: http://answers.yahoo.com/ +.. _StackOverflow: http://stackoverflow.com/ +.. _CNPROG: http://cnprog.com +.. _askbot: http://pypi.python.org/pypi/askbot +.. _django-1.1.2: http://www.djangoproject.com/download/1.1.2/tarball/ +.. _django-debug-toolbar: http://github.com/robhudson/django-debug-toolbar +.. _South: http://www.aeracode.org/releases/south/ +.. _recaptcha-client: http://code.google.com/p/django-recaptcha/ +.. _markdown2: http://code.google.com/p/python-markdown2/ +.. _html5lib: http://code.google.com/p/html5lib/ +.. _python-openid: http://github.com/openid/python-openid +.. _django-keyedcache: http://bitbucket.org/bkroeze/django-keyedcache/src +.. _django-threaded-multihost: http://bitbucket.org/bkroeze/django-threaded-multihost/src +.. _mysql-python-win: +.. _mysql-python: http://sourceforge.net/projects/mysql-python/ +.. _settings.py: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/settings.py +.. _urls.py: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/urls.py +.. _cron: http://www.unixgeeks.org/security/newbie/unix/cron-1.html +.. _mod_wsgi: http://code.google.com/p/modwsgi/ +.. _django.wsgi: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/setup_templates/django.wsgi +.. _forum: http://askbot.org +.. _askbot_cron_job: http://github.com/ASKBOT/askbot-devel/blob/master/askbot/cron/askbot_cron_job |