Kforge under Debian Etch
========================

Quickstart
==========

External dependencies
---------------------
Kforge requires a more recent version of python-routes than that included in the
etch archive.
A suitable version can be obtained from backports as follows:
Add
	deb http://www.backports.org/debian etch-backports main contrib non-free
to your apt sources

	#aptitude update
	#aptitude -t etch-backports install python-routes


Simple database configuration
------------------------------
Kforge requires a postgresql or mysql database. The wordpress plugin requires a
mysql database (the rest of kforge may use postgres if you wish)

If you use a local database server (on the same machine as kforge) the database
setup can be automated :
For postgres:
	#aptitude install postgresql-8.1 kforge-db-postgres
For mysql:

	#aptitude install mysql-server kforge-db-mysql

Note that the kforge packages do NOT depend on the database server packages
in case you wish to use a database server on another machine.

Plugin installation
-------------------
Install as many of the plugin packages as you require:
	kforge-mailman
	kforge-moinmoin
	kforge-svn
	kforge-trac
	kforge-wordpress
	kforge-www

Instance creation
-----------------
A kforge instance is a group of kforge products hosted by a single apache
virtual server and sharing a database.

To create a kforge instance run
	#kforge-instance create <instance-name>

This will create an instance using the virtual server name of
<instance-name>-<hostname>
where <hostname> is the result of the hostname(1) command on your machine.

If you wish to specify a virtual servername you may use
	#kforge-instance create --servername=<server-name> <instance-name>

You must ensure your clients correctly resolve your server name.

The apache configuration file is generated in
	/etc/apache2/sites-available/kforge-<instance-name>
and may be modified if required.

The default database will be used and a random password generated.
The instance configuration file is generated in
	/etc/kforge/instances/<instance-name>.conf
This file is only readable by root and the kforge group as it contains the
database password

Instance configuration
----------------------
Further instance configuration is performed using the kforge web interface

Instance deletion
-----------------
A kforge instance may be deleted by
	#kforge-instance drop <instance-name>
WARNING: this drops the instance database and deletes all files associated
with the instance WITHOUT ASKING FOR CONFIRMATION.

Plugin installation
-------------------
New kforge plugins may be installed after instance creation however they
will need to be enabled in the web interface for each project to be available

Plugin deletion
----------------
Removing a plugin (with aptitude remove or aptitude purge) while kforge instances
are still present does not currently delete the database tables used by the plugin
This needs some more work...

Advanced Database configuration
===============================
If you wish to use a database server on another machine you must first
manually create a kforge user for each instance you wish to use.
The kforge packages do not support automatic database creation in this case
since this would require the DBA password and for the server to allow remote
DBA access.

Then create a configuration file in /etc/kforge/db/mysql or /etc/kforge/db/postges
like this
# local=>server on local machine with automatic database creation
# manual=>administrator configuration
DB_MODE=manual

DB_TYPE=postgres (or mysql)

# Hostnaame of database server
DB_HOST=your.database.server

# Database name for kforge instance
DB_NAME=kforge_${instance_name}

# Database user for kforge instance
DB_USER=kforge_${instance_name}

# Password used to connect to database as kforge user
DB_PASSWORD=your_database_password

You can name the file as you like.

Then create your kforge instances with
	#kforge-instance create --dbtype=postgres|mysql \
	--dbname=<name of your config file with no path> \
	<instance-name>

You can make these options the defaults by setting up the symbolic links
	/etc/kforge/db/default -> postgres | mysql
	/etc/kforge/db/mysql/default -> default mysql database
	/etc/kforge/db/postgres/default -> default postgres database

Files
=====
The main files used by kforge are

/etc/kforge/db/			Database configuration
/etc/kforge/kforge.conf.new	Template configuration for new instances
/etc/kforge/instances		Instance configuration files (auto generated)
/usr/share/kforge/instances	Instance template files
/var/lib/kforge/instances/<instance-name>	Per instance dynamic data
/var/lib/kforge/plugins				Per plugin dynamic data
/var/log/kforge			Log files