# The KForge Guide

  1. Version
  2. Introduction
    1. About this Guide
    2. Overview ofthe KForge System
  3. Using KForge
    1. Create a New User
    2. Creating a Project
    3. Project Services
  4. Administering KForge
    1. Download and Installation
    2. A KForge Instance
    3. KForge Files
    4. Administering the KForge Domain Model
    5. The Admin User
    6. Plugins
    7. Themes

## Version

This guide is for KForge v0.12.

## Introduction

### About this Guide ###

This is guide to KForge. It is separated into a section for administrators and
a section for users of KForge. If you have a question that isn't answered here
please post them on the [KForge website][kforge] or on the kforge-user mailing
list: <http://lists.okfn.org/mailman/listinfo/kforge-user>. 

[kforge]: http://www.kforgeproject.com/

### Overview of the KForge System ###

KForge is a system for managing users, projects and the services associated
with projects such as websites, wikis, task-trackers, and repositories.

A KForge installation configured at <your.domain.com> will provide two separate
web interfaces (note that these would both prefixed with http:// or https://):

Admin interface at: admin.<your.domain.com>

Project interfact at: project.<your.domain.com>

Depending on how the instance is configured one of these instances (by
default the admin inteface) will also appear at <your.domain.com> and
www.<your.domain.com>.


## Using KForge ##

### Creating a New User ###

To create a new user

  1. Go to the registration page and fill in your details
  2. Submit the form
  3. Your user account will be automatically created (Note: there will be no
     validation or confirmation email)

#### The Visitor User ####

The system creates a visitor user named 'visitor'.

### Creating a Project ###

  1. Log in if you aren't logged in already
  2. Go to 'Your Page' by clicking on menu button
  3. Click on start new project link from the project sidebar
  4. Fill in the details of the project and click submit
  5. Your new project will have been created and it will be listed in the
     project sidebar of 'Your Page'

#### Members ####

As project administrator you can create members using the member subpage. To
make a user a member of a project they must have registered and you must know
their username (not their full name).

### Roles and Permissions ###

There are 4 roles available to users on the system in relation to any given project:

  1. **Administrator**: administrator have complete control of a project. They may
     create and delete members, assign roles, create and delete services and even
     delete the project itself.
  2. **Developer**: developers are full members of a project and may get full
     access to project services. However they may not administer the project in
     any way (for example they cannot create or delete members)
  3. **Friend**: A friend of a project may access project services to read them
     but may not write to them
  4. **Visitor**: visitors have minimal access to a project. They may not
     access project services and may only view that information about a project
     that is world-readable. By default users of the KForge system are
     allocated to the visitor role in relation to a project (whether they are
     members or not)

#### Setting the role for non-members project ####

You can set the default role for all non-members of a project to X by:

  1. Making the visitor user (name is visitor) a member of your project
  2. Setting the role of visitor to X

NB: non-members includes both registered and non-registered users

### Project Services ###

A project service is an instance of a plugin and it is the way external tools
are provided in KForge. So for example there are plugins for svn (subversion),
trac, moinmoin etc. By creating a svn or trac service for your project you
create an associated subversion repository or trac environment.

Usually you can associate multiple services of a given type with your project
so that you can have multiple repositories, multiple wikis etc. However some
plugins may only have a single instance associate with a project -- they may
only be 'on' or 'off'. For example the www plugin and the dav plugin are like
this (see below).

#### Creating ####

As the administrator of a project you can create, edit and delete project
services. You can do this by:

  1. Selecting the project
  2. Clicking on the Services link in the secondary menu bar at the top
  3. You should now be presented with a page listing the current active project
     services as well as option to create new ones
    * Note: the name you use for the service will be used as part of the url by
      which it is accessed (see below) so bear this in mind when choosing it.

#### Accessing Project Services ####

Project services are available under the project subdomain:
http://project.<domain-name>/

A specific service are located at the url: /<project-name>/<service-name>/

So for example a svn (subversion) service called 'repo' in project
'annakarenina' would be located at: 

  * http://project.<domain-name>/annakarenina/svn/repo/

Access control to project services follows the setup already described in the
Roles and Permissions section

#### Project Services Provided ####

**Note:** The system administrator may hot have enabled all of these service types on your installation.

  * dav: by creating a dav service you enable dav access to your project
    directory. You access the dav service via /<project-name>/dav/
    * Unlike other services the name of this service does not affect its url
      and so your are strongly encouraged to name the service 'dav'
  * www: by creating a www service you enable the project to have a home page
    at /<project-name>/.
    * Unlike other services the name of this service does not affect its url
      and so your are strongly encouraged to name the service 'dav'
    * To find out how to upload web pages see the howto below
  * svn: by creating a svn service you create a [subversion][] repository.
  * moin: by a creating a moin service you create a [moinmoin wiki][moinmoin]
  * trac: by creating a trac service you create a [trac installation][trac].
  * wordpress: by creating a wordpress service you create a [wordpress blog][wordpress].
  * mailman: by creating a mailman service you create a [mailman mailing list][mailman] with name <project-name>-<service-name>.

[subversion]: http://subversion.tigris.org/
[moinmoin]: http://moinmoin.wikiwikiweb.de/
[trac]: http://trac.edgewall.org/
[wordpress]: http://www.wordpress.org/
[mailman]: http://www.list.org/

#### Howtos ####

##### Creating a Project Website and Uploading Files To It #####

Your project website url is at http(s)://<project-host>/<project-name>/

  1. Enable the dav and www plugins for your project by creating a dav and www
     service for your project (see above)
  2. Now access the dav service at <project-url>/dav/ using a dav client of
     some kind (there are lots of these available, just google to find one)
  3. You should now be able to see various subdirectories related to the plugin
     types of the services enabled on your project. In particular you should see a
     www directory. Content from this directory is made available at your project
     website url. For example
     * if you create a file index.html in the www subdirectory viewable from
       dav then
     * this will show up at <project-url>/index.html
  4. Thus to upload content to your website just use your dav client to upload
     it into the www subdirectory
  5. That's it!


## Administering KForge ##

### Download and Installation ###

Please see <http://www.kforgeproject.com/download/>.

### A KForge Instance ###

KForge is designed so that you can have multiple KForge 'instances' running
simultaneously on any given machine. This is useful if you would like to run
several different sites all using KForge on the same system.

As an administrator your first task after installing the KForge code will be to
create a working KForge instance. This is covered in detail in the installation
guide so we will not cover it again here.

### The Admin User ###

By default on installation the system creates a user account with the
Administrator role with:

  * username: admin
  * password: pass
  * email: kforge-admin@<your-domain-name>
  
It is **strongly recommended** that you update this password **immediately**.

You can make any user a system administrator by setting their personal role to
Administrator.

#### KForge Files ####

A KForge 'instance' has various files associated with it:

1. Configuration files
   1. The main configuration file -- a template version is provided in etc/kforge.conf.new. See the installation instructions for more details
   2. An auto-generated apache configuration file. See the installation instructions for more details. 

2. Log files: the directory for these is set in the main configuration file.
   1. kforge.log   # logging from code
   2. apache.*     # various apache log files

3. Plugin data: base directory for this data is set in the main configuration file.

4. Per-project data: base directory for this data is set in the main configuration file.

In the case of project data the layout on disk is:

        <project-name>/  # all project data not in the db is stored under here
          <plugin-name>/
            <service-id>
            ...
          ...
        <project-name2>
        ....

So for example if you want to find the data for a subversion repository called
mysvn with id 9 in project myproject you would look in:

    <your-project-data-directory>/myproject/svn/9

### Administering the KForge Domain Model ###

As an administrator you will often want to administer the domain objects in a
given KForge instance such as:

  * Users (Persons)
  * Projects
  * Access control objects such as:
    * Protection Objects
    * Roles
    * Permissions
  * Plugin and Service objects (Services are instances of plugins)

You can adminster the domain model in 2 ways.

#### 1. Via the Command Line Interface ####

This is done by invoking a python shell and directly accessing the KForge
domain model. For more information please run:

  $ kforge-admin help shell

#### 2. Via the Web Interface ####

There is an web interface for system administrators available at /admin in the
admin view: http://admin.<your.domain.com>/admin/

### Plugins ###

Plugins provide a way to extend KForge and provide extra functionality. In
particular all services are provided via plugins. Thus adding and removing
plugins is a task that you will be likely to encounter as an administrator.

To install a plugin:

  1. Download the plugin package 
  2. Unpack the plugin package and follow the install instructions
  3. Enable the plugin for your particular instance by creating the plugin in
     the domain model using either the command line or web administrator
     interface (see above)
     
Note: many plugins are shipped pre-installed with KForge and for these you can
skip steps 1 and 2 (and usually 3 as well).

To remove a plugin from a running instance delete it from the domain model.

Warning: you will not be able to delete a plugin if it is being used.

### Themes ###

The KForge theme is defined by:

  * the django templates as found in the template directory (this is set in the
    config file)
  * the styling as found in the media directory (usually
    /usr/share/kforge/www/media but check in the config file)

If you want to create a new theme you should:

  1. Create a new template and media directory (probaby best done by copying
     the existing directories)
  2. Edit the necessary files (To understand how the templates work you should
     read up on django templates at the django site:
     http://www.djangoproject.com/)
  3. Edit the config file (etc/kforge.conf) to use your new directories
  4. Rebuild the configuration and reload apache

For example:

  * if you wish to change the basic look and feel of all pages you start by
    editing master.html in the base template directory.

  * if you wanted to change the text on the front page of the site edit
    index.html in the base template directory