# Kagemai installation guide

This document describes how to install Kagemai.

Kagemai requires a Web server and Ruby to run; however, their installation is not explained here. Also, this document assumes that you are using Apache as your Web server. Please substitute directions as appropriate for your operating environment.

## Contents

## Quick start

This section describes how to get Kagemai up and running quickly.

1. Extract the Kagemai archive file to a Web-accessible location.

         $ cd /home/fukuoka/public_html
         $ tar xfvz kagemai-0.8.7.tar.gz
         $ mv kagemai-0.8.7 kagemai

2. Set permissions so that the Web server can write to the directory where guest.cgi is located. In step 4, a settings file called kagemai.conf will be created there.
   (If su_exec is enabled, this step is probably not needed.)
3. Access html/guest.cgi from a Web browser.
   (Example: http:/www.example.net/~fukuoka/kagemai/html/guest.cgi)
   If *.cgi files are not being handled properly, configure your .htaccess file.

         $ cat html/.htaccess
         Options +ExecCGI
         AddHandler cgi-script .cgi

4. In "Admin" -> "Change global settings", set the following variables appropriately:

   home_url | Home page for the site
   project_dir | Location where project data will be saved

   If the directory specified in project_dir does not exist, set permissions to let the Web server can create the directory. Alternatively, create the directory in advance, then set its permissions so that the Web server can write to it.
   (If su_exec is enabled, this step is probably not needed.)
5. Create a project through "Admin" -> "Create a project".
6. Restrict access to user.cgi and admin.cgi as necessary. Use html/dot.htaccess as a reference.

         $ cat html/.htaccess
         <Files "*.conf*">
           deny from all
         </Files>

         <Files user.cgi>
           AuthName      Kagemai-User
           AuthType      Basic
           AuthUserFile  /etc/kagemai/user.passwd
           Require       valid-user
         </Files>

         <Files admin.cgi>
           AuthName      Kagemai-Administrator
           AuthType      Basic
           AuthUserFile  /etc/kagemai/admin.passwd
           Require       valid-user
         </Files>

## Installing Kagemai with install_en.rb

This section explains how to install Kagemai using install_en.rb.

1. Create a kagemai group.
   If you are receiving data via e-mail as well as via the Web interface, create a group for accessing Kagemai data.

         # groupadd kagemai

   Next, add the Web server user (example: apache) to the newly-created group.

         # gpasswd -a apache kagemai

2. Edit install_en.rb.
   Edit the following variables in install_en.rb as needed:

   $user | User ID for the data directory
   $group | Group ID for the data directory
   $root_dir | Directory containing libraries and resource files for Kagemai
   $html_dir | Web-accessible directory where the CGI scripts are placed
   $data_dir | Directory where project data is store
   $passwd_dir | Directory where passwords used in .htaccess authentication are placed

   If $user and $group do not need to be set, comment them out.
   If $user is set, but not $group, the permissions of the data directory and its files will be set to 0755 and 0644 respectively. Other directories will be set to 0775 and their files to 0664.
3. Run install_en.rb.
   When you are finished editing install_en.rb, execute it (after becoming root, if necessary).

         # ruby install_en.rb

4. Verify functionality.
   Access guest.cgi and verify that it displays properly.
   If it displays properly, try creating a new project through "Admin" -> "Create a new project". If you can create a project, try submitting a bug report in that project.

## Creating graphs with GD and GDChart

If you install GD and GDChart, you can display report summary graphs. If you do not need graphs, the steps below are not needed.

(The libraries mentioned below are also available at http://www.daifukuya.com/archive/kagemai/lib/. While the library versions there have been confirmed to work with Kagemai, they are likely not the latest versions.)

1. Install GD.
   Download GD from http://www.boutell.com/gd/ and install it.
   You will need to have PNG and TrueType fonts enabled in GD. To enable PNG and TrueType font support, libpng, zlib, and FreeType need to be installed beforehand. (If you run the configure script in GD 2.0.15, it will display whether or not these libraries are configured.)

         $ tar xfvz gd-2.0.15.tar.gz
         $ cd gd-2.0.15
         $ ./configure
         ...(snip)...
         ** Configuration summary for gd 2.0.15:

          Support for PNG library:          yes
          Support for JPEG library:         yes
          Support for Freetype 2.x library: yes
          Support for Xpm library:          yes
         ...(snip)...
         $ make
         $ sudo make install

2. Install Ruby/GD.
   Download Ruby/GD from http://raa.ruby-lang.org/list.rhtml?name=ruby-gd and install it.
   You will need to specify --with-ttf and --with-freetype when you configure it.

         $ tar xfvz ruby-GD-0.7.4.tar.gz
         $ cd ruby-GD-0.7.4
         $ ruby extconf.rb --with-ttf --with-freetype
         $ make
         $ sudo make install

3. Install Ruby/GDChart.
   Download Ruby/GDChart from http://raa.ruby-lang.org/list.rhtml?name=ruby-gdchart and install it. (Ruby/GDChart is an extension library for GDChart, but GDChart is included in the Ruby/GDChart archive.)

         $ tar xfvz ruby-gdchart-0.0.9-beta.tar.gz
         $ cd ruby-gdchart-0.0.9-beta
         $ ruby extconf.rb
         $ make
         $ sudo make install

4. Configure enable_gdchart, gd_font, and gd_charset.
   In "Change global settings", set enable-gdchart to true, set gd-font to the path for your TrueType fonts, and set gd_charset to UTF-8.
5. Verify functionality
   Open a project summary page where one or more reports have been submitted, and verify that the graphs display correctly.
   Because the summary page is cached, changes made may not be reflected if you do not submit a report or reply, or if you do not delete the file cache/cache.pstore in the project directory.

## Using mod_ruby

You can run Kagemai with mod_ruby. Using dot.htaccess as a guide, configure guest.cgi, user.cgi, and admin.cgi so that they start up through mod_ruby.

If you will change the *.cgi extensions to *.rbx, for example, do the following:

1. Copy guest.cgi, user.cgi, and admin.cgi to *.rbx files.

         $ cp -p guest.cgi guest.rbx
         $ cp -p user.cgi user.rbx
         $ cp -p admin.cgi admin.rbx

2. Access admin.cgi and change the following items in "Global settings":

         guest_mode_cgi : guest.rbx
         user_mode_cgi  : user.rbx
         admin_mode_cgi : admin.rbx

3. Try accessing guest.rbx.

## Using PostgreSQL

This section explains the configuration needed to save data using PostgreSQL. (However, it does not explain how to install PostgreSQL itself.) If you are not saving data using PostgreSQL, the configuration below is not necessary.

1. Install Ruby/Postgres.
   Download Ruby/Postgres from http://www.postgresql.jp/interfaces/ruby/ and install it.

          $ tar xfvz ruby-postgres-0.7.1.tar.gz
          $ cd ruby-postgres-0.7.1
          $ ruby extconf.rb
          $ make
          $ su
          # make install

2. Install Ruby/DBI.
   Download Ruby/DBI from http://rubyforge.org/projects/ruby-dbi/ and install it.

         $ tar xfvz ruby-dbi-all-0.1.0.tar.gz
         $ cd ruby-dbi-all
         $ ruby setup.rb config --with=dbi,dbd_pg,dbd_mysql
         $ ruby setup.rb setup
         $ su
         # ruby setup.rb install

3. Create an account for Kagemai to use in PostgreSQL.

         $ createuser kagemai
         Shall the new role be a superuser? (y/n) n
         Shall the new role be allowed to create databases? (y/n) n
         Shall the new role be allowed to create more new roles? (y/n) n
         CREATE ROLE

4. Create a database for Kagemai in PostgreSQL.

         $ createdb kagemai

5. In "Change global settings", set enable_postgres to true.
   Configure the settings below as well.

   postgres_host | Name of the host where PostgreSQL runs. If you are using Unix domain sockets, specify the directory for the socket. The default is /tmp.
   postgres_port | Port number (if you are connecting via TCP)
   postgres_user | Username for the PostgreSQL account
   postgres_pass | Password for the PostgreSQL account
   mysql_dbname | Name of the Kagemai database in PostgreSQL

6. Confirm that you can select PostgresStore as a method for saving data when you create a project.
7. Select PostgresStore as the data saving method, then try to create a project.

## Using MySQL

This section explains the necessary configuration for saving data using MySQL.

1. Download MySQL/Ruby or Ruby/MySQL.
   Download either library from http://tmtm.org/en/mysql/ and install it.
2. Install Ruby/DBI in the same way you would for for PostgreSQL.
3. Create a database for Kagemai in MySQL.

         $ mysql -u root -p
         mysql> create database kagemai;

4. Create a user for Kagemai in MySQL.
The user must be able to access the database.

      mysql> grant all to on kagemai.* to kagemai@localhost;

Set passwords as needed.
5. Set enable_mysql to true in "Change global settings".
   Configure the settings below as well.

   mysql_host | Name of the host where MySQL runs. The default is localhost.
   mysql_port | Port number for MySQL. The default is 3306.
   mysql_user | Username for the MySQL account
   mysql_pass | Password for the MySQL account
   mysql_dbname | Name of the Kagemai database in MySQL

6. Confirm that you can select Kagemai::MySQLStore as a method for saving data when you create a project.
7. Select Kagemai::MySQLStore as the data saving method, then try to create a project.

## Using SQL Server

To use SQL Server, the configuration steps below are necessary.

1. Create an account for Kagemai in SQL Server. This user must have "create database" rights.
2. In the ODBC settings on the machine where Kagemai will run, set the SQL Server in the system DNS.
3. Set enable_mssql to true in "Change global settings".
4. Enter the system DNS name in mssql_dns.
5. Enter the SQL Server username/password in mssql_user and mssql_pass.
6. Confirm that you can select Kagemai::MSSQLStore as a method for saving data when you create a project.
7. Select Kagemai::MSSQLStore as the data saving method, then try to create a project.

## Mail interface settings

To use the mail interface, you will first have to set three variables in mailrf.rb: kagemai_root, config_file, and $LOGFILE. (If you installed Kagemai using install_en.rb, suitable values were already set at the time of installation.)

When you create a project, an include file for that project will be created that can be used by sendmail or other mail programs.

      $ cat /var/lib/kagemai/project/test/include
      "|/usr/bin/ruby /usr/local/kagemai/bin/mailif.rb test"

Here, "test" is the project ID.

If you are using sendmail, edit /etc/aliases to call that file, then update /etc/aliases.db.

      # grep 'test-bugs' /etc/aliases
      test-bugs: :include:/var/lib/kagemai/project/test/include
      # /usr/bin/newaliases

By default, the include file is placed in a group-writable directory. Move it to another directory and use it there if necessary.

In the default mail template, the URL for the submitted report is inserted. To have the correct URL inserted, set base_url appropriately in "Change global settings." base_url is the URL of the directory containing guest.cgi. For example, if guest.cgi is at 'http://www.example.net/kagemai/guest.cgi', set base_url to 'http://www.example.net/kagemai/'.

Kagemai automatically figures out whether submitted mail is a new report or a reply to an existing report by using the "Subject" and "In-Reply-To" headers.

## Manual installation example

This section gives an installation example in which all of the configuration is done manually.

1. Decide on the location of installation directories.

         Kagemai libraries: /usr/local/kagemai
         CGI scripts: /var/www/html/kagemai
         Data directory: /var/lib/kagemai

   We will assume that files placed in /var/www/html/kagemai are accessible via the URL http://www.example.net/kagemai.
2. Create directories and copy files.

         $ tar xfvz kagemai-0.8.7.tar.gz
         $ cd kagemai-0.8.7

         $ su
         # mkdir /usr/local/kagemai
         # mkdir /var/www/html/kagemai
         # mkdir /var/lib/kagemai
         # mkdir /var/lib/kagemai/project

         # cp -pr bin /usr/local/kagemai
         # cp -pr lib /usr/local/kagemai
         # cp -pr resource /usr/local/kagemai
         # cp -p html/* /var/www/html/kagemai

3. Edit paths within files.
   Edit the Ruby path, kagemai_root, and config_file in the files below.
   - /usr/local/kagemai/bin/convert.rb
   - /usr/local/kagemai/bin/mailif.rb
   - /usr/local/kagemai/bin/migrate.rb
   - /var/www/html/kagemai/guest.cgi
   - /var/www/html/kagemai/user.cgi
   - /var/www/html/kagemai/admin.cgi
   Here, we will assume that kagemai_root is /usr/local/kagemai and that config_file is /var/www/html/kagemai/kagemai.conf. We will also set $LOGFILE in mailrf.rb to be /var/lib/kagemai/mailif.log.
4. Add the kagemai group and set permissions.

         # groupadd kagemai
         # cd /var/lib
         # chgrp -R kagemai kagemai
         # chmod -R 02770 kagemai

   Also, add apache to the kagemai group.

         # gpasswd -a apache kagemai

5. Edit the variables below in "Change global settings":

         project_dir : /var/lib/kagemai
         base_url    : http://www.example.net/kagemai/

And you're done.