Administration guide

Karma works with manifests and modules. Manifests consist of a certain amount of modules. A manifests is defined in an XML file, which defines the properties of the manifest and the modules the manifest contains. Modules are stored in a version control system, and identified by a location attribute in the manifest file (see below). This attribute is used by Karma to locate the correct version control system (its location).

The manifest and location configuration is stored in a version control repository as well. The so-called `manifest-store` and `location-store`. Both of these will have to be present for Karma to actually do something usefull.

In the case of CVS you have to create a manifests and locations module in your repository. It is also possible to create one module (say karma) and create a manifests and locations module under that.

Next to the manifests and locations module you have to define a modules module. In this module the actual modules are stored. I.e. : 

CVSROOT/
manifests/
locations/
modules/

or: 

CVSROOT/
karma/
    manifests/
    locations/
    modules/

The manifest store

Software modules are grouped in a so-called manifest. These manifests are xml files, following the `http://www.toolforge.org/specifications/karma/manifest.dtd` definition. Karma is capable of checking out these manifest files from a (CVS) repository. The local checkout of this module (which must be named : manifests) is called the 'manifest-store'. During startup of Karma, the manifest-store configuration will be checked and asked for if missing (see getting started).

See the Reference Documentation for more information on the configuration aspects of the manifest store.

Create a file helloworld.xml and add it to your manifest store (check it in into your manifest store module in a CVS repository: 

  
<?xml version="1.0"?>

<manifest type="development" version="1-0">
  <modules>
    <module name="helloworld" location="local"/>
  </modules>
</manifest>

The location store

Each module has a location. Right now, all modules have a location identifying a CVS repository. Locations are configured in xml files, following the http://www.toolforge.org/specifications/karma/location.dtd definition. Karma is capable of checking out these location files from a (CVS) repository. The local checkout of this module (which must be named : locations) is called the 'location-store'. During startup of Karma, the location-store configuration will be checked and asked for if missing. You have to provide these properties to Karma which will be written in $USER_HOME/.karma/<working-context>/workingcontext.properties.

See the reference documentation for more information on the configuration aspects of the location store.

The following could be your starter location. Create a file locations.xml and add it to your location store in the CVS repository: 


  
<?xml version="1.0"?>

<loc:locations>

  <loc:location type="cvs-repository" id="local">
    <loc:protocol>local</loc:protocol>
    <loc:host>localhost</loc:host>
    <loc:port>2401</loc:port>
    <loc:repository>/home/cvs</loc:repository>
    <loc:module-offset></loc:module-offset>
  </loc:location>

</loc:locations>

The mapping between the manifest and the location is made via id="local".

Authentication configuration

Version control repositories, such as CVS, can be behind an authentication layer. If so, you will need a username and password. Karma maps each location to authentication data. This authentication data is (Karma R1.0) required to be in a file called $USER_HOME/.cvspass. If you have ever used CVS command-line tools, you might have it on your system already. For each location (a CVS location will create a CVSROOT from it), a line should be created in the .cvspass file. This includes the location configuration for the manifest-store and the location-store. A general .cvspass file looks like: 

/1 :pserver:asmedes@cvs.toolforge.nl:2401/cvs/karma B$#H er_9
/1 :pserver:asmedes@cvs.toolforge.nl:2418/cvs/cli B$^G er_9

The scrambled password is stored in this file as well. Ask your administrator (or send us an email support@toolforge.org for more info if you haven't got a clue...).

The authentication data that Karma requires has to be available in $USER_HOME/.karma, in a file called authenticators.xml. The following snippet shows the authenticators.xml that maps to the location you configured above : 

  
<?xml version="1.0"?>

<authenticators>
  <authenticator working-context="default" id="local" username="asmedes"/>
</authenticators>

Note that asmedes is the username in the CVS repository, although it is not required for a CVS repository that is local (the :local: protocol), Karma still needs it to keep track of who did what (history).