KForge is distributed as the Python package 'kforge'. 

Please report any problems, or other feedback, here:

    mailto:kforge-dev@lists.okfn.org


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-auth-pgsql
    libapache2-mod-macro
    libapache2-mod-ssl
    libapache2-mod-python
    
    django
      * check out the code:
        svn co http://code.djangoproject.com/svn/django/trunk/
      * cd to the directory you checkouted to then:
        python setup.py install

KForge Installation Instructions
++++++++++++++++++++++++++++++++

Steps:
  1. Install the system
  2. Environment Configuration
  3. Create the database
  4. Edit and build configuration

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

By default the system will install to

  <home>/kforge

Where <home> is the users home directory. This directory will be referred to
as BASE

Alternative Installation Location
=================================

To install kforge in an alternative location run:

  $ python setup.py install --home=BASE

where BASE will be location of the alternative installation.

Examples of alternative installations include:

  $ python setup.py install --home=~/kforge
  $ python setup.py install --home=~/kforge-test


Configuration
*************

Environment
===========

You need to set these environment variables in your kforge programs'
environment:

    $ export KFORGEHOME=BASE
    $ export PYTHONPATH=$KFORGEHOME/lib/python

where BASE is the location of the installation (as above).

Appending the kforge bin/ directory to $PATH makes running command line
utilities easier:

    $ export PATH=$PATH:$KFORGEHOME/bin

Setting File Permissions
========================

For web access to work for kforge you must allow the web server (apache)
access to kforge files. To do this we recommend doing the following:

Note that this will probably need super user access
A suitable umask value UMASK to allow group access is 00x where x = 2 (default)
or 7

  1. Set umask for <kforge-user> so that group also has write permissions. Add
  the following line to the your environment setup (e.g. ~/.bashrc)u
    $ umask UMASK
  
  2. Giving web user access to kforge installation by adding <apache-user> to
  <kforge-user> group:
    $ usermod -G<kforge-user-group> <apache-user>
  
  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<version>):
      umask UMASK
      
  4. Give group access to existing files and make sure new files and
  directories remain in the <kforge-user-group> by setting sgid
    $ chmod g+wX -R BASE

Generating the KForge Database
******************************

Kforge uses the PostgreSQL database system. Setting up the kforge database
has the following steps:
  1. Create (or have) a postgresql user: USER
  2. Postgresql access configuration
  2. Create the kforge database DATABASE

1. Create (or have) a postgresql user
-------------------------------------

Before creating a database you will need to have a postgresql user
  * make sure this user has a password
  * it is useful if this user has 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 <user-name>

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    DATABASE     USER     127.0.0.1  255.255.255.255    md5
host    template1    USER     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:
    
3. Create the Kforge Database
-----------------------------
    * Edit etc/kforge.conf to ensure that the [db] section their reflects the
    username and password and the db name (see section below for info on
    setting up and editing the configuration file)
    * Having done all of this you can then just run:
      $ bin/kforge-db create


Edit and build configuration
****************************

Copy (or move) the template configuration file etc/kforge.conf.new to
etc/kforge.conf and then open it in your favourite text editor.

You will probably want to set following variables:
  * domain_name
  * service_name

Once done you will want to build dependent application configuration by
running:

  $ bin/kforge-config-rebuild

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.


Testing the KForge Installation
+++++++++++++++++++++++++++++++

To test the installation, run:

  $ kforge-test-run

**However** note that you may need to do the following:
  * Make sure you have sudo permissions to reload the apache webserver
  * have webunit installed