diff options
Diffstat (limited to 'forum/documentation/INSTALL')
| -rw-r--r-- | forum/documentation/INSTALL | 284 |
1 files changed, 284 insertions, 0 deletions
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 |