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 or on the kforge-user mailing list: http://lists.okfn.org/mailman/listinfo/kforge-user.

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:

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.

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

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:

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://{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. For details see the help::

$ kforge-admin help plugin

Themes

The KForge theme is defined by:

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: