# 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.15.

## 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, unsurprisingly,
appear at http://{your.domain.com} (and https://{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)

NB: On initialization the system automatically creates a user named 'visitor'
to make it easier to configure permissions. See the section on Roles and
Permissions below for more information.

### 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 at: http://{domain-name}/{project-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://{domain-name}/annakarenina/repo/

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

#### Project Services Shipped with KForge ####

Wherever the relevant plugin has been installed and enabled the corresponding project service will be available. Below is the list of plugins/services shipped with KForge (other service plugins may be to provided by 3rd parties). Note that your KForge administrator may **not** have enabled all of the corresponding plugins on your installation in which case the service will **not** be available.

  * 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
  * 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'
  * mailman: by creating a mailman service you create a [mailman mailing
  list][mailman] with name {project-name}-{service-name}.
  * mercurial: by creating a mercurial service you a [mercurial/hg](http://www.selenic.com/mercurial/wiki/) repository.
  * moin: by a creating a moin service you create a [moinmoin wiki][moinmoin]
  * svn: by creating a svn service you create a [subversion][] repository.
  * trac: by creating a trac service you create a [trac installation][trac].
  * wordpress: by creating a wordpress service you create a [wordpress blog][wordpress].

[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)://{domain-name}/{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 machine.

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 [INSTALL
file][install] so we will not cover it again here.

[install]:http://www.kforgeproject.com/doc/install

### 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

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

There's more information about using the KForge shell here:
http://knowledgeforge.net/kforge/svn/trunk/docs/cli_shell.txt

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

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

### Plugins ###

Plugins are a way to extend KForge and provide extra functionality. In
particular all project services are provided via plugins. Thus, installing and
enabling/disabling plugins is a task that you will be likely to encounter as an
administrator. There are two steps involved in getting a plugin working:

  1. Installing the plugin on the system.
  2. Enabling/disabling this plugin on a particular KForge instance/service.

#### Installation ####

This step is usually entirely independent of KForge (you are just installing
the plugin as a python application). Instructions on how to do so should be
provided with the plugin. Note that all plugins shipped with KForge are
automatically installed when you install the KForge system itself.

#### Enabling/Disabling ####

Once installed at the system level plugins must be enabled/disabled for each
running KForge instance/service. Enabling/disabling of plugins (as well as
other plugin-related activities is done via) the `kforge-admin plugin` comand.

Project administrators can only create new project services with enabled
plugins. Please note, disabling a plugin which has been used to create project
services will not disable those services.

For more details see the help::

    $ kforge-admin help plugin


### Themes ###

The KForge theme is defined by:

  * the CSS and images in the media directory (config file: 'media_dir')
  * the HTML in the templates directory (config file: 'templates_dir')

If you want to create a new theme you should:

  1. Create new media and template directories (probaby best done by copying
     the existing directories).
  2. Edit the necessary files (to understand how the templates work please
     read up on Django templates: http://www.djangoproject.com/).
  3. Adjust your KForge configuration file to use your new directories.
  4. Regenerate the Apache configuration file and reload apache.

For example:

  * If you wanted to change the colours, use Firebug and adjust .css files.

  * If you wanted to change the text on the front page of the site edit
    snippets/introduction.html, snippets/sitesummary.html, and 
    snippets/userlinks.html in the base template directory.

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

