This guide is for seperated into a section for administrators and a section for users of KForge. If you have a question that isn't answered here please ask on the MailingLists.

[[TableOfContents]]

----

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

Along with a command line interface KForge also provides a web interface to allow users to administer projects and services.

= Administering KForge =

This guide is relevant to KForge v0.10

== Getting Started ==
  * KforgeDownload -- how to get the software
  * KforgeInstall -- how to install (and uninstall) the software

== The Command Line Interface ==

You can all KForge functionality locally via its command line interface.

The KForge command line interface (CLI) is available via the kforge-admin script (found in the bin/ directory).

To find out what commands are available, their syntax and options please read the help file (type: kforge-admin --help)

== The Admin User ==

By default on installation the system creates a user account with the SystemAdministrator role with name: admin, password: pass. It is recommended that you update this password '''immediately'''.

== Plugins ==

KForge can be extended via plugins and 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. Get hold of the plugin package (many plugins are shipped pre-installed with KForge)
  2. Unpack the plugin package and follow the install instructions
  3. Run: $ kforge-admin create plugin <plugin-name>

To remove a plugin simply run:
{{{
$ kforge-admin delete plugin <plugin-name>
}}}

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 var/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 Guest User ===

The system creates a guest user named 'guest'.

== To Create a Project ==

  1. Log in if you aren't 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 (short) 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. Guest: guests 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 guest 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 Guest user (name=guest) a member of your project
  2. Setting the role of guest to X

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

== Project Services ==

A project service is an instance of 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 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

=== 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>/<plugin-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 ===

  * www: by creating a www service you enable the project to have a home page at /<project-name>/
    * to upload web pages you will also want to enable the dav plugin and then use dav to upload files to the www subdirectory of your project directory
  * dav: by creating a dav service you enable dav access to your project directory. You access the dav service via /<project-name>/dav/
  * svn: by creating a svn service you create a subversion repository (location as specified above)
  * moin: by a creating a moin service you a moinmoin wiki
  * trac: by creating a trac service you create a trac project