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
Installing Kagemai with install_en.rb
Creating graphs with GD and GDChart
Using mod_ruby
Using PostgreSQL
Using MySQL
Using SQL Server
Mail interface settings
Manual installation example

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_urlHome page for the site
    project_dirLocation 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.
  5. The user must be able to access the database.
      mysql> grant all to on kagemai.* to kagemai@localhost;
    
    Set passwords as needed.
  6. 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
  7. Confirm that you can select Kagemai::MySQLStore as a method for saving data when you create a project.
  8. 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.
    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.