KForge is distributed as the Python package 'kforge'. Please report any problems, or other feedback, here: mailto:kforge-dev@lists.okfn.org Quickstart ++++++++++ The full install is listed below but to summarize: 1. Install all necessary applications (apache/postgresql/python/... see below) 2. Create a postgresql user for KForge 2. Install the KForge code: $ python setup.py install --home= 3. Set shell environment: $ export KFORGEHOME= $ export PYTHONPATH=$KFORGEHOME/lib/python $ export DJANGO_SETTINGS_MODULE=kforge.django.settings.main 4. Create and edit the KForge configuration file: * copy etc/kforge.conf.new to etc/kforge.conf * edit as necessary (see below and configuration file itself for details) 5. Generate the KForge db: $ bin/kforge-db create 6. Build apache config and symlink it so that it will be used * bin/kforge-config-rebuild * symlink KFORGEHOME/etc/httpd.conf so that webserver uses it (do NOT copy) 7. Final touches: * set file permissions/ownerships (www-user is the user under which the web server runs) $ chown -R : KFORGEHOME * allow for auto-reloading of web server configuration (see below) 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-auth-pgsql libapache2-mod-macro libapache2-mod-ssl libapache2-mod-python 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 By default the system will install to /kforge Where 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 Configure the Shell Environment ******************************* You need to set these environment variables in your kforge programs' environment: $ export KFORGEHOME= $ export PYTHONPATH=$KFORGEHOME/lib/python $ export DJANGO_SETTINGS_MODULE=kforge.django.settings.main where is the location of the installation (as above). Edit the KForge Configuration File ********************************** 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 * edit the [db] section to reflect the choices for your database Generate the KForge Database **************************** $ bin/kforge-db create If you want to replace an existing db (warning: this will delete all existing data): $ bin/kforge-db rebuild Build Apache Configuration ************************** $ 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. 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