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.13.

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)

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

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

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

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

    Note that, by default, the install instructions for a given plugin are kept in the docstring at the top of the plugin’s main *.py file. You can read these instructions either from the python shell or by opening the file in a text editor. For example, to read the install instructions for the svn (subversion plugin) via the python shell you would do the following

     # open a python shell
 $ python
 >>> import kforge.plugin.svn
 # a simple help(kforge.plugin.svn) will not work because of missing
 # 'features' so do this instead
 >>> x = kforge.plugin.svn.__doc__
 >>> print x
  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 step 1.

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 has any associated services.

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: