# Kagemai user's guide

This document is a guide for people using Kagemai.

## Contents

## What is Kagemai?

Kagemai is a bug tracking system written in Ruby. It aims to be a easy-to-use system for small projects or individual to-do lists.

To make Kagemai as easy to use as possible, it is distributed as a single working unit (with the exception of Ruby). You can use all of its basic functions right away, even if you do not get libraries from other locations, compile extension libraries, or set up a database. Also, unlike many other bug tracking systems that require e-mail usage, Kagemai works with no problem even if you cannot use e-mail. And once you install Kagemai, it will let you perform administration tasks without having to log into the server (although this feature is not quite sufficiently implemented yet).

As of January 15, 2005, one can do the following things with Kagemai:

- Submit bug reports and replies via Web forms or e-mail
- Set the status and severity of reports when submitting or replying to them
- Notify project administrators and other e-mail addresses when a report or reply is submitted
- Search for reports by keyword, field value, or date
- Split reports if they contain information on multiple bugs
- Syndicate the contents of bug reports and replies with RSS
- Create, delete, and change settings for projects using a Web interface
- Customize report fields (status, severity, owner, etc.) for each project
- Customize every page of the user interface for each project
- Turn customized projects into templates and reuse them in other projects
- Save data using text files, PostgreSQL, MySQL, or SQL server, and change the save format at any time
- Handle Japanese

Kagemai is in its early stages of development. However, if you are looking for a bug tracking system that can be used for individual, small-scale projects, it will be worth it to try out Kagemai. Since installing Kagemai is simple, you will not lose much if you try it out and end up not liking it. If you try it and find that it does not suit you, please send e-mail to the kagemai-users mailing list saying what you did not like. Even if you liked Kagemai and decided to use it, your thoughts, suggestions, and bug reports for Kagemai itself are greatly appreciated. Both positive and negative opinions spur Kagemai's progress.

## License

Kagemai is free software; it can be used and redistributed under the terms of the GNU General Public License.

The libraries below are also included in the Kagemai distribution. Please abide by their licenses when redistributing them.

- ERB <http://www2a.biglobe.ne.jp/~seki/ruby/index.en.html>
- rubymail <http://www.lickey.com/rubymail/>
- xmlscan-snapshot-20011123 <http://www.blue.sky.or.jp/atelier/ruby/xmlscan/old/>

## Installing Kagemai

Please refer to the installation guide for instructions on installing Kagemai.

## User categories

Kagemai divides its users into guests, users, and admins.

Guests
  Restricted to a few functions. They can create reports, post replies, and search for reports, but may not be able to change certain report fields, such as the status. (This depends on the settings for the project.)
Users
  In addition to having all the privileges of guests, users can also change report fields such as status.
Admins
  The administrators of Kagemai. In addition to having all the privileges of guests and users, admins can create, delete, and change the settings of projects.

Kagemai distinguishes guests, users, and admins by the CGI script they call (guest.cgi, user.cgi, and admin.cgi, respectively). Kagemai does not perform any user authentication of its own; instead, restrict access to these scripts as needed using the functions of your Web server.

## Global settings

Global settings affect all of Kagemai. They are saved in the configuration file specified in guest.cgi (kagemai.conf). The default global setting values are written in config.rb, but you will normally not ever need to change config.rb directly.

If you carelessly change the values of language, action_dir, resource_dir, default_template_dir, message_bundle_name, or admin_mode_cgi, Kagemai will no longer function. If this happens, edit kagemai.conf directly and remove the parts that specify those settings.

### Global setting options

maintenance_mode | When this is set to true, Kagemai will be placed in maintenance mode. In maintenance mode, only admins can access Kagemai.
language | Working language for Kagemai. For this option, select the name of a resource directory under resource_dir (mentioned below). Currently, you can select "en" (English) and "ja" (Japanese).
charset | Character set for displaying text. (Note: if you use Japanese, you can only use the EUC-JP encoding for now.)
home_url | URL of the "Home" link placed in the navigation bar on every page.
base_url | URL where guest.cgi is located. This will be used as the URL of the bug tracking system in notification e-mails.
action_dir | Directory where the action scripts called by the CGIs reside. Scripts placed in this directory are loaded automatically. Normally, you will not need to change this setting.
project_dir | Directory where project data is stored. You will need to set the permissions of this directory such that the Web server can write data to it.
resource_dir | Directory where error messages, page templates, and project templates are placed. Normally, you will not need to change this directory.
mailer | Class used to send mail. Currently, you can specify Kagemai::SmtpMailer, Kagemai::MailCommandMailer, and Kagemai::SendmailCommandMailer.
smtp_server | Name of the SMTP server used for sending mail. Because this value will be used as part of the Message-ID in the mail header, specify as much of a FQDN (fully-qualified domain name) as possible.
smtp_port | Port number for the SMTP server.
mail_command | If you specified Kagemai::MailCommandMailer or Kagemai::SendmailCommandMailer for mailer, this specifies the command used to send mail.
default_template_dir | Directory where the default templates for every page are placed. Normally, you will not need to edit this value.
message_bundle_name | Name of the file where error messages are defined. Normally, you will not need to change this setting.
default_store | The initially-selected save format when you create a project. If you have set up database support in Kagemai, you can select that for a save format as well.
default_template | ID of the initially-selected project template when you create a project. You can select simple or normal.
subject_id_figure | Number of digits used for padding when the report ID is inserted into the subject of an e-mail. For example, if the project ID is test_project, the report ID is 1, and this option is set to 4, [test_project:00001] will be added to the beginning of the subject.
fold_column | Number of characters at which long text lines will be wrapped in report displays on the Web and in sent e-mail.
css_url | URL for the default style sheet.
max_attachment_size | Maximum size (in kilobytes) for file attachments. If this is set to 0, there will be no size limit.
guest_mode_cgi | Name of the script used for guest mode. If you change the name of guest.cgi, set this option.
user_mode_cgi | Name of the script used for user mode. If you change the name of user.cgi, set this option.
admin_mode_cgi | Name of the script used for admin mode. If you change the name of admin.cgi, set this option.
use_javascript | Whether or not to use Javascript for forms. Set this to true or false. Currently, Javascript is used in forms for field creation and field editing.
allow_mail_body_command | Whether or not one can change the status of reports via e-mail. Set this to true or false.
search_form_method | Whether to use GET or POST when sending a search form.
pretty_html | Whether or not to fix up generated HTML. Note that it will take some time for Kagemai to fix up HTML before displaying it.
enable_postgres | Whether or not to enable PostgreSQL as a save format. (Set this to true or false.) If you set this to true, install Ruby/Postgres and Ruby/DBI first, as described in the installation guide.
postgres_host | Host name of the PostgreSQL server used to save data. If you are connecting via Unix domain sockets, specify the directory of the Unix domain socket.
postgres_port | Port number of the PostgreSQL server, if you are connecting via TCP.
postgres_user | Username of the PostgreSQL user that will save project data. The specified user must have privileges to create databases.
postgres_pass | Password for the PostgreSQL user that will save data.
postgres_opts | Options passed to the PostgreSQL server when you connect to it.
enable_mssql | Whether or not SQL Server as a format for saving data. (Set this to true or false.)
mssql_dsn | Specifies the ODBC DSN.
mssql_user | Username for connecting to SQL Server.
mssql_pass | Password for connecting to SQL Server.
enable_mysql | Whether or not to enable MySQL as a format for saving data. (Set this to true or false.)
mysql_host | Hostname of the MySQL server.
mysql_port | Port number of the MySQL server.
mysql_user | Username for connecting to MySQL.
mysql_pass | Password for connecting to MySQL.
mysql_dbname | Name of the MySQL database being used.
enable_gdchart | Whether or not to enable graphing using GD and GDChart. (Set this to true or false.) If you set this to true, install Ruby/GD and Ruby/GDChart first, as described in the installation guide.
gd_font | Font used in creating graphs. Specify an appropriate TrueType font.
gd_charset | Character encoding used in graph creation.
rss_feed_title | Title of the RSS feed for the bug tracking system

### Mail configuration

In Kagemai, you can use SMTP, the mail command, or the sendmail command for sending e-mail. You can specify which one to use in the global setting mailer.

Kagemai::SmtpMailer | Send mail via SMTP. If you have specified SmtpMailer, you will need to set smtp_server and smtp_port correctly as well.
Kagemai::MailCommandMailer | Send mail using the mail command. If you have specified MailCommandMailer, you will need to set mail_command and the path to the mail command correctly as well. You can send mail even in environments where an SMTP server cannot be used. However, a disadvantage is that you cannot specify the sender name via the mail command; it will end up being the ID of the user running the mail process.
Kagemai::SendmailCommandMailer | Send mail using the sendmail command. If you have specified SendMailCommandMailer, you will need to set mail_command and the path to the sendmail command correctly as well. Because you can set the sender name with the sendmail command, you can use the e-mail address of the person who submitted the report/reply for the sender name.

## Managing projects

### Creating projects

Below are the options available for creating a new project.

ID | ID for Kagemai to identify the project. Information for each project is saved in a directory with the same name as the project's ID, under the directory specified in the global setting project_dir. You can only use alphanumeric characters for the ID; in addition, you cannot use "CVS" for an ID.
Name | Name for end users to identify the project. Select a name that is easy to understand.
Description | Description that will appear in the projects list.
Admin address | E-mail address of the project administrator. If this is set, it will be used as the sender address for notification e-mails. Make sure to set this to a valid e-mail address. If the admin address is not set, the e-mail notification function will be disabled.
Submission address | E-mail address for receiving reports. The e-mail address specified here will be placed in the Reply-To line of notification e-mails.
Notification address | E-mail address(es) that you would like to have notified when reports or replies are submitted. Mail addresses specified here will be placed in the Bcc line of notification e-mails.
Line wrap width | Number of characters at which long text lines will be wrapped in report displays on the Web and in sent e-mail.
Bug ID padding | Number of digits used for padding when the report ID is inserted into the subject of an e-mail. For example, if the project ID is test_project, the report ID is 1, and this option is set to 4, [test_project:00001] will be added to the beginning of the subject.
Stylesheet URL | URL for the project's style sheet.
Save format | Format for saving data. The default is to save data for one report in one text file; you can select this behavior by selecting Kagemai::XMLFileStore. If you set up support for PostgreSQL, SQL Server, or MySQL, you will be able to select them as save formats. You can also change the data save format after creating the project.
Template | Template for the project. Report forms differ for each template.
Top page | Items that will appear on the main page for the project.

With the exception of ID and Template, you can change any of the options after creating the project.

### Deleting projects

When deleting a project, you can delete the project completely, or delete the project without deleting its data.

However, if you delete a project that saved data using PostgreSQL, but do not delete its data, you cannot create a new project that has the same ID as the previous project and saves data using PostgreSQL. (You can select PostgreSQL as a save format, but it will result in an error.)

### Configuring projects

Other than for ID and template, you can change the options of a project after creating it.

If there are a large number of reports, it is recommended that you save data using a database and that you do not display the bug list on the front page.

### Backing up data

If you need to back up project data, save the files in the global setting project_dir. If you are using a database to store project data, it will need to be backed up as well.

### Important security notes

This may be obvious, but if the Web server user can read and write project data, anyone who can configure CGIs to run with that user's rights can manage project data. There are several ways to avoid this situation:

- Use suexec and have the CGIs run under that user's account
- Use suexec and set the permissions of the project data directories so that only a certain user can read and write from them
- Use databases for project data that needs to be protected
- Do not create non-admin user accounts on the server where Kagemai is located

Investigate other options as needed.

## Customization

### Customizing fields

Kagemai allows you to customize the report fields for every project. This section explains the options for fields and options for individual choices in a field.

You can set the options below for every field.

Save the value of this field in a cookie | Whether or not to save the entered value in a cookie, if the user has chosen to use cookies.
Check e-mail address | Whether or not to check if the submitted value is a valid e-mail address. If you perform the check, values that are not valid e-mail addresses will return an error.
Make this field a report property | Whether or not to make this field a report property. Status, priority, and report-specific values are set to be report properties. The sender's e-mail address and the message contents are not.
Allow guests to change this field | If the field is a report property, this specifies whether or not guests can alter the field. If guests are not allowed to change the value, you cannot have it appear on the new report form for guests or on the reply form.
Allow users to change this field | If the field is a report property, this specifies whether or not users can alter the field. If users are not allowed to change this value, you cannot have it appear on the new report form for users or on the reply form. (Admins can change the values of any field, even if guests and users cannot.)
Display as a report index item | Whether or not to display the field in the report index on the main page or the search results page. This only applies to fields that are report properties.
Display in log message headers | Whether or not to display the field in the log message headers on the report details page.
Display on a separate line in log message headers | Whether or not to display the field in message log headers on a separate line. For example, you can customize headers to show the e-mail address on a separate line, and status and priorities together on another line.
Hide from guests | Whether or not to show the field to guests. When this is set to on, guests will be unable to see the field.
Use as an index on the project home page | If the field is a single-selection or a multiple-selection box and is set to be a report property, this specifies whether or not to create a report list on the top page based on the field, with reports separated by field value. Set this if you want a list of reports separated by status, for example.
Display as a radio button | If the field is a single-selection field, this specifies whether or not to display the field as a checkmark. When this is off, it will be a list box.
Display as a checkbox | If the field is a multiple-selection field, this specifies whether or not to display the field as a set of checkboxes. When this is off, it will be a list box.

You can always add fields and change the settings of fields. However, if reports have already been submitted for a project, you cannot add fields that lack a default value.

In addition, a field choice editing form will be displayed after for selection fields after they have been added or edited. You can change the following items for each choice in the field:

Short description | Short description of the choice. This will become a heading if the field is used as an index on the top page.
Long description | Long description of the choice. If the field is used as an index, this will be displayed as a supplementary description.
Display on the top page | Whether or not to display the choice on the top page. If the field is not used as an index, this setting will have no effect.

### Customizing page templates

If you place files with the same name as the default page templates in the template directory for a project, they will be used first when the page is created.

Refer to the template file list and the source code to find out how each template file is used.

### Individual scripts for projects

*.rb files placed in the script directory for a project will automatically be loaded and evaluated when a CGI script is run. By placing scripts in the script directory, you can change the rendering methods for report fields or manage messages at the time of submission, among other things.

At the moment, the following experimental scripts have been prepared to handle functions that cannot be done generically:

color.rb | Changes the display color of field choices depending on their value.
replace.rb | Replaces characters in fields when HTML is generated. It is used to replace the "@" symbol with "at" in e-mail addresses.
email_message.rb | Sends mail to the owner of a report after it has been assigned an owner.
depend.rb | Converts the ID of the bug entered in the "Depends on" field into a link to that bug.
change_status.rb | Automatically changes the values of fields when a message is submitted. (Because the script depends on the content of the field choices, if you comment it all out, it will no longer do anything.)

All scripts in the script directory will be run at safe level 1.

### Creating project templates

You can turn settings from customized projects (fields, templates, scripts, etc.) intoa project template and reuse them.

- Create a directory under the template directory (resource/en/template). The directory name will become the ID of the template.

        $ cd /usr/local/kagemai/resource/en/template
        $ mkdir my_template

- Copy reporttype.xml, template/*, and script/*.rb from the project you wish to turn into a template.

        $ cp /var/lib/kagemai/project/custom/reporttype.xml my_template
        $ cp -r /var/lib/kagemai/project/custom/template my_template
        $ cp -r /var/lib/kagemai/project/custom/script my_template

- In reporttype.xml, edit the id and name of the ReportType element. Also, edit the description element, inserting a description of the template.

        $ head -7 reporttype.xml
        <?xml version="1.0" encoding="UTF-8"?>

        <ReportType id="my_template" name="My template">
          <description>
            This is my customized template!
          </description>

- Load the project creation form and verify that the new template is listed as an option.

## Changing a report's status via e-mail

If you are submitting reports and replies via e-mail and have set the global setting allow_mail_body_command to be true, you can change field values such as the status within the body of e-mails.

To do this, begin a line with "# kagemai : ", then enter the name of the field and the new value, separated by an equals sign.

      # kagemai : Status = Accepted

You can also specify the field by its ID.

      # kagemai : status = Accepted

Lines that are recognized as field changing commands will be deleted from the message when it is received.

Currently, anyone can change the values of fields via e-mail; Kagemai does not distinguish who the user is. In addition, it is possible to end up setting a field to a value that is not a valid choice. (For example, even if "New", "Fixed", and "Resolved" are the only selections for "Status", it is possible to set "Status" to "Accepted" via e-mail.) If these limitations are a problem, set allow_mail_body_command to false.

## Graphing with MRTG

Kagemai has an action that will return the number of unresolved and unresolved bugs in plain-text format so that you can graph trends using MRTG.

If you have a project with an id of "test" and access guest.cgi with "mrtg" specified as the action (example: http://www.example.net/kagemai/guest.cgi?project=test&action=mrtg&t=2 ), it will return a plain-text document with the number of unresolved bugs on the first line and the number of resolved bugs on the second line.

Refer to the mrtg_en/mrtg.cfg file in this distribution for information on MRTG configuration. (You will have to move the mrtg_en folder to mrtg to display graphs in English; the default mrtg directory is for Japanese users.) Using these numbers, you can create graphs like this (Japanese).

## Using Kagemai for multiple bug tracking systems

You can use a single installation of Kagemai for multiple bug tracking systems.

First, create a Web-accessible directory, and copy guest.cgi, user.cgi, and admin.cgi to it. Copy kagemai.css and wallpaper.gif as well, if needed.

      $ mkdir public_html/my_bts
      $ cp /var/www/html/kagemai/*.cgi public_html/my_bts
      $ cp /var/www/html/kagemai/kagemai.css public_html/my_bts
      $ cp /var/www/html/kagemai/wallpaper.gif public_html/my_bts

Next, edit the config_file setting in guest.cgi.

      $ vi guest.cgi
      $ grep 'config_file' guest.cgi
      config_file  = '/home/fukuoka/public_html/my_bts/kagemai.conf'

Access admin.cgi and change the global setting project_dir. Then, it will be possible to use Kagemai for a separate bug tracking system.