KForge is distributed as the Python package 'kforge'. Please report any problems, or other feedback, here: mailto:kforge-dev@lists.okfn.org Quickstart ++++++++++ Full details for installation are listed below in ``Full Installation Instructions''. 1. Preliminaries **************** 1. Install all dependencies (python/apache/postgresql/python/... see below) 2. Create a postgresql user for KForge 2. Install KForge system ************************ $ python setup.py install 3. Create a KForge instance/environment *************************************** 1. Initialize an environment at $ kforge-admin --env= data create $ export KFORGEHOME= 2. Edit the KForge configuration file at /etc/kforge.conf * see below and configuration file itself for details 3. Generate the KForge db: $ kforge-admin db create * if you have already created a db use 'rebuild' instead of 'create' 4. Build apache config and symlink it so that it will be used * $ kforge-admin www build * symlink /etc/httpd.conf so that webserver uses it (do NOT copy) 5. Final touches: * set file permissions/ownerships (www-user is the user under which the web server runs) $ chown -R : * allow for auto-reloading of web server configuration (see below) 6. Restart/reload the webserver $ bin/kforge-admin www reload For developers/testers only: **************************** 1. $ export DJANGO_SETTINGS_MODULE=kforge.django.settings.main 2. $ bin/kforge-test Full Installation Instructions ++++++++++++++++++++++++++++++ KForge Package Dependencies *************************** kforge depends on these packages. Please make sure you have them (or equivalents) installed on your system. (NB: these are the Debian names and might be slightly different on your system) postgresql (object-relational SQL database management system) postgresql-client (front-end programs for PostgreSQL) python-psycopg (Python DB-API interface to PostgreSQL) python-sqlobject (Python module for SQLObject) libapache2-mod-python libapache2-mod-ssl [optional] django * check out the code (revision 304): svn co http://code.djangoproject.com/svn/django/trunk/ -r304 * cd to the directory you checked out, and run: python setup.py install Create a Postgresql User ************************ 1. Before creating a database you will need to have a postgresql user * make sure this user has a password * this user must have permission to create databases * the following command will do this but will probably require superuser access. See the postgres manual for more details $ createuser --pwprompt --createdb 2. Postgresql Access Configuration * Make sure postgresql is configured to give you access to the database you are going to create e.g. pg_hba.conf must have something like: host 127.0.0.1 255.255.255.255 md5 host template1 127.0.0.1 255.255.255.255 md5 NB: the second of these is so that the user can create and delete dbs If you do change this file, be sure to restart or reload the PostgreSQL daemon Install the System ****************** Download and untar latest kforge source, change into the distribution root directory (directory containing this INSTALL file), and run: $ python setup.py install Create a KForge Instance/Environment ************************************ $ kforge-admin --env= data create You need to set these environment variables in your kforge programs' environment: $ export KFORGEHOME= If you plan to run tests: $ export DJANGO_SETTINGS_MODULE=kforge.django.settings.main Edit the KForge Configuration File ********************************** Open etc/kforge.conf in your favourite text editor and take a look at the comments there. Generate the KForge Database **************************** $ kforge-admin db create If you want to replace an existing db (warning: this will delete all existing data): $ kforge-admin db rebuild Build Apache Configuration ************************** $ kforge-admin www build For apache you need to ensure the generated configuration at: etc/httpd.conf is loaded by the web server. You must symlink to this file rather than copy it as it often updated. Final Touches ************* Setting File Permissions ======================== For web access to work for kforge you must allow the web server (apache) access to kforge files. To do this you have two options: 1. Have web user own all kforge files: $ chown -R : This may cause problems if you then wish to run command line utilities to administer KForge since you may not have permission to write to files and directories owned by the web-user. 2. Allow for dual access by the kforge user and the web-user. Allowing for Dual Access ------------------------ A suitable umask value UMASK to allow group access is 00x where x = 2 (default) or 7 1. Set umask for so that group also has write permissions. Add the following line to the your environment setup (e.g. ~/.bashrc) $ umask UMASK 2. Giving web user access to kforge installation by adding to group: $ usermod -G 3. Set umask for apache to allow group access: * add the following to apache startup script (usually /usr/sbin/apachectl or /usr/sbin/apache2ctl -- you can find it referenced in /etc/init.d/apache): umask UMASK 4. Give group access to existing files and make sure new files and directories remain in the by setting sgid $ chmod g+wX -R BASE Allowing for Auto-Reloading of the Apache Configuration ======================================================= It is occasionally necessary for the KForge system to update the apache configuration file (for example when new services are added). For these changes to take effect it is then necessary for apache to reload the configuration. There are two options for how this is done: Automatically(default) ---------------------- The job is done by the apacheconfig plugin. In order for this to work the user which owns the apache process must be able to reload the configuration. Specifically it must be able to run the 'reload_apache' command specified in the [www] section of the configuration. You can normally achieve this by adding something to your /etc/sudoers file: > Cmnd_Alias APACHE = > [....] > ALL =NOPASSWD: APACHE Manually -------- Reload the apache config by hand or using a cron job on a regular basis. If this is the case you should remove the apacheconfig plugin which is installed by default and performs the automatic reloading. Testing the KForge Installation +++++++++++++++++++++++++++++++ To test the installation, run: $ bin/kforge-test **However** note that you may need to do the following: * Make sure you have sudo permissions to reload the apache webserver * have webunit installed