The KForge Guide (v0.11)

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

Version

This guide is for KForge v0.11.

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 will provide two separate web interfaces (note that these would both prefixed with http:// or https://):

Admin interface at: admin.

Project interfact at: project.

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

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.

Basic Layout

A KForge ‘instance’ is laid out on disk at follows:

etc/
  kforge.conf  # kforge configuration file
  httpd.conf   # apache configuration file (automatically generated)
var/
  log/           # all log files
    kforge.log   # logging from code
    apache.*     # various apache log files
  plugin_data/   # directory for any plugin specific data
  project_data/
    <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 (relative to the root directory of your KForge instance):

var/project_data/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
  • 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./admin/

The Admin User

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

  • username: admin
  • password: pass

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.

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

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

A specific service are located at the url: ///

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

  • http://project./annakarenina/svn/repo/

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

Project Services Provided

  • dav: by creating a dav service you enable dav access to your project directory. You access the dav service via //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 //
    • 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 (location as specified above)
  • moin: by a creating a moin service you create a moinmoin wiki
  • trac: by creating a trac service you create a trac project

Howtos

Creating a Project Website and Uploading Files To It

Your project website url is at http(s):////

  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 /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 /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!
Posted in Uncategorized | No Comments »

Leave a Reply