このドキュメントは、影舞を利用してみようと思っている人への手引きです。
影舞とは？
ライセンス
インストール
利用者の分類
全体の設定
全体設定のオプション
メール送信の設定について
プロジェクトの管理
プロジェクトの作成
プロジェクトの削除
プロジェクトの設定変更
データのバックアップ
セキュリティ上の注意点
カスタマイズ
フィールドのカスタマイズ
ページテンプレートのカスタマイズ
プロジェクト固有スクリプト
プロジェクトテンプレートの登録
メールでの状態変更
MRTGでのグラフ化
複数の BTS としての利用
影舞は Ruby によってかかれた、 いわゆるバグトラッキングシステム(Bug Tracking System: BTS)です。 小規模なプロジェクトや個人的な ToDo リストなどにも容易に利用できるように、 簡単に使えるシステムを目指しています。
できるだけ簡単に利用できるようにするため、Ruby を除けば単体で動作する形で配布しています。 別の場所からライブラリを拾い集めたり、拡張ライブラリをコンパイルしたり、 データベースをセットアップしたりしなくても、基本的な機能はすべて利用できます。 また、いくつかの BTS ではメールの使用が必須になっていますが、 影舞はメールの使用を前提にはしていません。メールが使えない状況でも問題なく動作します。 そして、一度インストールした後は、できるだけサーバにログインしなくても管理できるようにしています。 （まだ十分ではないかもしれませんが。）
現在(2008/02/22)のところ実現されている主な機能は以下のとおりです。
影舞はまだまだ初期段階にあります。 しかし、個人的な、あるいは、小規模なプロジェクトで利用するバグトラッキングシステムを 求めているなら、影舞を試してみる価値はあるでしょう。 影舞のインストールは簡単ですから、試して気に入らなくても失うものはそう多くはないはずです。 もし試して気に入らなかったら、 どうか、なにが気に入らなかったかを kagemai-users ML で教えてください。 気に入って使う場合にも、利用しての感想、提案、 まだまだ残っているに違いないバグの報告などを送っていただけると嬉しいです。 肯定的な意見も、否定的な意見も、いずれも影舞の進化の糧にさせていただきます。
影舞はフリーソフトウェアです。
GNU General Public License Version 2 の元で利用や再配布が可能です。
また、影舞の配布物には以下のライブラリが含まれています。 これらのライブラリの再配布など関しては、各ライブラリのライセンスに従ってください。
影舞のインストールについては、インストール方法を参照してください。
影舞では、利用者をゲスト、ユーザ、管理者に分類しています。
ゲスト、ユーザ、管理者はそれぞれ呼び出す CGI スクリプト (guest.cgi, user.cgi, admin.cgi)によって区別しています。 必要に応じて、Web サーバの機能を用いてそれぞれのファイルへのアクセスを制限してください。
全体に影響する設定項目です。 全体の設定は、guest.cgi で指定した設定ファイル(kagemai.conf) ファイルに保存されます。 全体設定のデフォルト値は config.rb に書かれていますが、通常は config.rb を直接書き換える必要はありません。
設定項目のうち、language, action_dir, resource_dir, default_template_dir, message_bundle_name, admin_mode_cgi については、不用意に書き換えると動作しなくなります。 これらの項目を設定して動作しなくなった場合には、 kagemai.conf を直接編集して、項目を設定している部分を削除してください。
| maintenance_mode | ture のとき、影舞をメンテナンスモードにします。メンテナンスモードでは、 管理者以外はアクセスできなくなります。 |
|---|---|
| language | 言語を指定します。この設定で、resource_dir の下に配置されたリソースを選択します。 いまのところは ja しか使えません。 |
| charset | 文字セットを指定します。いまのところ EUC-JP しか使えません。 |
| home_url | 各ページに表示されるナビゲータの、"ホーム" アンカーのリンク先を指定します。 |
| base_url | guest.cgi などが置かれている URL です。 メール送信時に、通知メール内で BTS の URL として使用されます。 |
| action_dir | CGI での動作を記述したスクリプトを配置しているディレクトリです。 このディレクトリに置かれたスクリプトは自動的にロードされます。 通常、このディレクトリの設定を変更する必要はありません。 |
| project_dir | プロジェクトのデータを保存するディレクトリです。 Web サーバがデータを書き込めるように、適切なパーミッションが設定されている必要があります。 |
| resource_dir | エラーメッセージなどや各ページのテンプレート、 プロジェクトのテンプレートが置かれているディレクトリです。 通常、このディレクトリの設定を変更する必要はありません。 |
| mailer | メール送信用のクラスを指定します。今のところ、Kagemai::SmtpMailer, Kagemai::MailCommandMailer, Kagemai::SendmailCommandMailer が指定できます。 |
| smtp_server | メールの送信に使用する SMTP サーバの名前です。 メールヘッダの Message-ID の一部として使用するので、できるだけ FQDN で指定してください。 |
| smtp_port | SMTP サーバのポート番号です。 |
| mail_command | mailer に Kagemai::MailCommandMailer もしくは Kagemai::SendmailCommandMailer を指定した場合に、送信に使用するコマンドを指定します。 |
| default_template_dir | 各ページのデフォルトのテンプレートが配置されているディレクトリの名前です。 通常、この設定を変更する必要はありません。 |
| message_bundle_name | エラーメッセージなどが定義されているファイルの名前です。 通常、この設定を変更する必要はありません。 |
| default_store | プロジェクトの作成時に、最初に選択されているデータ保存方法です。 PostgreSQL のセットアップをすれば、Kagemai::PostgresStore を指定することもできます。 |
| default_template | プロジェクトの作成時に、最初に選択されているプロジェクトのテンプレートIDです。 simple, normal, old などが指定できます。 |
| subject_id_figure | メール送信時に、メールのサブジェクトに挿入するレポートIDの桁数です。 プロジェクトID が test_project で、レポートID が 1、指定した桁数が 4 のときには、 [test_project:0001] がメールのサブジェクトの先頭につきます。 |
| fold_column | Web でのレポートの表示やメールでの送信時に、長いテキストを折り返す桁数です。 |
| css_url | デフォルトで使用するスタイルシートの URL です。 |
| max_attachment_size | 添付ファイルの上限サイズ(KBytes)です。0 を指定すると制限なしになります。 |
| guest_mode_cgi | ゲストモードの CGI スクリプトの名前です。 guest.cgi の名前を変更した場合に指定してください。 |
| user_mode_cgi | ユーザモードの CGI スクリプトの名前です。 user.cgi の名前を変更した場合に指定してください。 |
| admin_mode_cgi | 管理者モードの CGI スクリプトの名前です。 admin.cgi の名前を変更した場合に指定してください。 |
| use_javascript | フォームで Javascript を使用するかどうかです。true もしくは false を指定してください。 今のところ、フィールドの作成、編集フォームで Javascript を利用しています。 |
| allow_mail_body_command | メールでのレポートの状態変更などを許すかどうかです。 true もしくは false を指定してください。 |
| search_form_method | 検索フォームを送信するときに GET か POST のどちらを用いるかを指定します。 |
| pretty_html | 生成した HTML の整形を行うかどうかです。 整形を行うと、それなりに時間がかかります。 |
| enable_postgres | PostgreSQL を用いたデータ保存方法を有効にするかどうかです。 true もしくは false を指定してください。 true に設定する場合には、 最初にインストール方法に書いてあるように、 Ruby/Postgres や Ruby/DBI などを正しくインストールしてください。 |
| postgres_host | データの保存に使用する PostgreSQL のサーバのホスト名です。 Unix ドメインソケットで接続する場合には、 Unix ドメインソケットのディレクトリを指定してください。 |
| postgres_port | PostgreSQL に TCP で接続する場合のサーバのポート番号です。 |
| postgres_user | データの保存に使用する PostgreSQL のユーザ名です。 指定したユーザは、データベースを作成する権限を持っている必要があります。 |
| postgres_pass | データの保存に使用する PostgreSQL ユーザのパスワードです。 |
| postgres_opts | PostgreSQL のサーバに接続するときに、サーバに渡されるオプションです。 |
| enable_mssql | SQL Server によるデータ保存を有効にします |
| mssql_dsn | ODBC の DSN を指定します |
| mssql_user | SQL Server のユーザ名です |
| mssql_pass | SQL Server のパスワードです。 |
| enable_mysql | MySQL によるデータ保存を有効にします。 |
| mysql_host | 接続する MySQL のホスト名を指定します。 |
| mysql_port | 接続する MySQL のポート番号を指定します。 |
| mysql_user | MySQL の接続に用いるユーザ名を指定します。 |
| mysql_pass | MySQL に接続するユーザのパスワードを指定します。 |
| mysql_dbname | MySQL で使用するデータベースの名前を指定します。 |
| enable_gdchart | GD, GDChart を用いたグラフ作成を有効にするかどうかです。ture か false を指定してください。 true に視する場合には、 最初にインストール方法に書いてあるように、 GD, Ruby/GD, Ruby/GDChart をインストールしてください。 |
| gd_font | グラフ作成に用いるフォントです。日本語の TrueType フォントを指定してください。 |
| gd_charset | グラフ作成に用いる文字コードです。 |
| rss_feed_title | BTS全体のRSSフィードにつけるタイトルです。 |
影舞では、メールを送信するための方法として、SMTP, mail コマンド、 sendmail コマンドが利用できます。メールの送信方法は、全体設定の mailer で指定することができます。
| Kagemai::SmtpMailer | SMTP によってメールを送信します。SmtpMailer を指定した場合には、 smtp_server と smtp_port も正しく設定する必要があります。 |
|---|---|
| Kagemai::MailCommandMailer | mailコマンドを使用してメールを送信します。 MailCommandMailer を指定した場合には、 mail_command オプションで mail コマンドのパスを正しく設定する必要があります。 SMTP サーバが使用できない環境でもメールを送信できますが、 欠点として、mail コマンドでは送信者を指定することができないため、 送信時のプロセスのユーザが送信者になってしまいます。 |
| Kagemai::SendmailCommandMailer | sendmail コマンドを使用してメールを送信します。 SendmailCommandMailer を指定した場合には、 mail_command オプションで sendmail コマンドのパスを正しく設定する必要があります。 sendmail コマンドでは送信者の指定ができるため、 投稿した人のメールアドレスでメールが送信できます。 |
プロジェクト作成時の設定項目は以下の通りです。
| ID | 各プロジェクトを識別するための ID です。個々のプロジェクトの設定情報は、
全体設定で指定された project_dir 以下に、プロジェクト ID
と同じ名前のディレクトリが作成され、その中に保存されます。 ID には、英数字しか使用できません。また、'CVS' という ID は使用できません。 |
|---|---|
| 名前 | 各プロジェクトを利用者が識別するための名前です。 実際の利用者にわかりやすい名前をつけてください。 |
| 説明文 | プロジェクト一覧において、各プロジェクトを説明するための文章です。 |
| 管理者アドレス | 管理者のメールアドレスです。 指定されている場合には、通知メールの送信者として使用されます。 エラーメールを受け取るために、正しいアドレスを指定してください。 管理者のメールアドレスが指定されていない場合には、メールによる通知機能は off になります。 |
| 投稿用アドレス | レポートのメールでの投稿用のメールアドレスです。 ここに設定されたメールアドレスは、通知メールの Reply-To ヘッダに設定されます。 |
| 通知先アドレス | レポートが投稿されたときや、リプライが投稿されたときに、 必ずメールで通知を行いたいメールアドレスです。ここに設定されたメールアドレスは、 通知メールの Bcc として設定されます。 |
| テキストの折り返し桁数 | Web でのレポートの表示やメールでの送信時に、長いテキストを折り返す桁数です。 |
| バグIDの桁数 | メール送信時に、メールのサブジェクトに挿入するレポートIDの桁数です。 プロジェクトID が test_project で、レポートID が 1、指定した桁数が 4 のときには、 [test_project:0001] がメールのサブジェクトの先頭につきます。 |
| スタイルシートのURL | プロジェクトのスタイルシートの URL を指定します。 |
| 保存形式 | データの保存形式です。
デフォルトでは、１レポートを１つのテキストファイルに保存する、Kagemai::XMLFileStore
が選択できます。PostgreSQL 関係の設定を行えば、PostgreSQL にデータを保存する
Kagemai::PostgresStore が選択可能になります。 データの保存形式は、プロジェクト作成後にも変更可能です。 |
| テンプレート | プロジェクトのテンプレートです。 テンプレートごとに、レポートの形式などが異なります。 |
| トップページ | プロジェクトのトップページに表示する項目を選択します。 |
プロジェクトの ID とテンプレート以外は、プロジェクト作成後に変更することができます。
プロジェクトの削除には、完全な削除と、データを残した削除があります。
完全な削除を選択した場合には、データはすべて消去されます。 データを残す削除を選択した場合には、プロジェクトの一覧には表示されなくなりますが、 必要であれば後から復活させることもできます。
ただし、データの保存に PostgreSQL を使用しているプロジェクトでは、 データを残した削除を行った場合、それ以降、同じプロジェクトID を持つプロジェクトを作成するときに、データの保存形式として PostgreSQL を使用できなくなります。 （選択はできますが、エラーになります。）
プロジェクトの ID とテンプレート以外は、プロジェクト作成後に変更することができます。
投稿されたレポートの数が多くなってきた場合には、 トップページのバグのリストを表示しないようにしたり、 データの保存を PostgreSQL へ行うように変更するのをおすすめします。
データのバックアップが必要な場合には、全体の設定の project_dir で指定したディレクトリ以下のファイルを保存してください。 PostgreSQL を利用している場合には、 PostgreSQL のデータベースのバックアップも必要です。
プロジェクトのデータが Web サーバの権限で読み書きできるようになっている場合には、 当然のことながら、Web サーバの権限で動作する CGI などを設置できる人であれば、 そのプロジェクトのデータを操作することができます。
回避方法としては、
などが考えられます。必要に応じて検討してください。
影舞はプロジェクトごとにレポートのフィールドをカスタマイズすることができます。 ここでは、フィールドの設定項目のうちのオプションと、選択肢フィールド固有の設定について説明します。
各フィールドは、以下のオプションを指定できます。
| クッキーで値を保存する | 利用者がクッキーを使用するように選択したときに、 クッキーを使用して入力された値を保存するかどうかです。 |
|---|---|
| メールアドレスチェックを行う | 入力された値がメールアドレスとして正しいかをチェックするかどうかです。 チェックを行う場合には、メールアドレスとして正しくない値はエラーになります。 |
| レポート属性として扱う | フィールドをレポート属性にするかどうかです。 状態や優先度など、レポート固有の値は、レポートの属性として指定します。 送信者のメールアドレスやメッセージの内容などは、非レポート属性に指定します。 |
| ゲストによる変更を許可する | フィールドがレポート属性に指定されている場合に、 フィールドをゲストが変更できるかどうかを指定します。 ゲストによる変更を許さない場合には、ゲスト用の新規作成フォームや、 リプライフォームで、このフィールドの値を指定できません。 |
| ユーザによる変更を許可する | フィールドがレポート属性に指定されている場合に、 フィールドをユーザが変更できるかどうかを指定します。 ユーザによる変更を許さない場合には、ユーザ用の新規作成フォームや、 リプライフォームで、このフィールドの値を指定できません。 （ゲスト、ユーザの両方が変更できないように設定したフィールドの値であっても、 管理者は変更することができます。） |
| レポートのインデックス項目として表示する | トップページや検索結果でレポートのインデックスとして、 このフィールドの値を表示するかどうかです。レポート属性の場合のみ意味を持ちます。 |
| 履歴のヘッダに表示する | レポートの詳細表示の履歴において、 各メッセージのヘッダとしてこのフィールドの値を表示するかどうかです。 |
| 履歴のヘッダに一行で表示する | メッセージのヘッダとしてこのフィールドの値を表示するときに、 値を一行で表示するかどうかです。 このオプションにより、メールアドレスなどは一行に表示し、状態や優先度はまとめて表示する、 といったカスタマイズができます。 |
| ゲストに見せない | このフィールドをゲストにも見せるかどうかです。 on の時には、ゲストにはこのフィールド自体が見えなくなります。 |
| トップページで取り上げる | 単一選択肢、複数選択肢フィールドで指定できます。 フィールドがレポート属性に指定されているとき、トップページで、 選択肢別のインデックスを作成するかどうかです。 状態別などのインデックスを表示したい場合に指定します。 |
| ラジオボタンとして表示する | 単一選択肢フィールドで指定できます。 単一選択肢を、ラジオボタンにするかどうかです。 off の場合には、リストボックスになります。 |
| チェックボックスとして表示する | 複数選択肢フィールドで指定できます。 複数選択肢を、チェックボックスにするかどうかです。 off の場合には複数選択可能なリストボックスになります。 |
フィールドの追加や、設定の変更はいつでも行うことができます。 ただし、すでにレポートが投稿されているプロジェクトにおいては、 デフォルト値を持たないフィールドは追加できません。
また、選択肢フィールドでは、フィールドの追加、設定の変更を行った後に、 選択肢の編集フォームが表示されます。 選択肢の編集フォームでは、各選択肢ごとに以下の項目を設定できます。
| 短い説明 | 選択肢の短い説明です。 トップページにインデックスを表示するときの見出しになります。 |
|---|---|
| 長い説明 | 選択肢の長い説明です。 トップページにインデックスを表示するときに、補足の説明として表示されます。 |
| トップページへの表示 | この選択肢をトップページに表示するかどうかです。 フィールドの設定で、 選択肢フィールドをトップページに取り上げるように設定されていなければ効果を持ちません。 |
各プロジェクトディレクトリ内の template ディレクトリに、 デフォルトのページのテンプレートファイルと同じ名前のファイルを置くと、 ページを作成するときに優先的に使用されます。
各テンプレートファイルが何に使用されているかは、 ソースコードやテンプレートファイル一覧を参考にしてください。
各プロジェクトディレクトリ内の、script ディレクトリに置かれた *.rb ファイルは、 CGI スクリプトを実行するときに、自動的にロードして評価されます。 script ディレクトリにスクリプトを置くことによって、 レポートのフィールドのレンダリング方法を変更したり、 メッセージ投稿時に処理を実行させたりできます。
今のところ、汎用的にできなかった処理を実現するために、以下のような スクリプトを実験的に用意しています。
| color.rb | 選択肢の値ごとに表示色を変更します。 |
|---|---|
| replace.rb | HTML を生成するときに、フィールド中の文字列を置き換えます。 メールアドレスの '@' を ' at ' に置き換えに使用しています。 |
| email_message.rb | リプライの投稿時に担当者が割り当てられているとき、 担当者にメールを送ります。 |
| depend.rb | "依存するバグ"フィールドに入力された数字を、 BTS 内の別のレポートID として、リンクに変換して表示します。 |
| change_status.rb | メッセージの投稿時に、フィールド値を自動的に変更します。 （選択肢の内容に依存するため、全体をコメントアウトして無効になっています。） |
script ディレクトリの各スクリプトは、セーフレベル 1 で eval されます。
カスタマイズしたプロジェクトの設定（フィールド、ページテンプレート、 スクリプトなど）を、プロジェクトのテンプレートとして登録し、 再利用することができます。
$ cd /usr/local/kagemai/resource/ja/template $ mkdir my_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
$ head -7 reporttype.xml
<?xml version="1.0" encoding="EUC-JP"?>
<ReportType id="my_template" name="マイテンプレート">
<description>
カスタマイズした私のテンプレートです。
</description>
レポートの新規投稿やリプライの投稿をメールで行う場合、 全体の設定で allow_mail_body_command が true に設定されているなら、 メールの本文で、状態の変更などフィールドの値を設定することができます。
設定を行うには、行を '# kagemai : ' で始め、 その後ろにフィールド名に対する代入を書きます。
# kagemai : 状態 = 受付済
また、フィールドID を指定することもできます。
# kagemai : status = 受付済
フィールドの設定コマンドとして認識された行は、受付時に削除されます。
メールによるフィールド値の設定は、今のところ利用者の識別などを行わずに、 誰でも行うことが可能になっています。 また、設定する値は、選択肢に存在しないものでも設定できてしまいます。 （例えば、“状態”フィールドの選択肢として、“新規”、“修正済み”、“完了” しかない場合でも、 “受付済”をメールによって設定できます。） こういった制限が問題になる場合には、allow_mail_body_command を false にしてください。
影舞には、未終了のバグ数、終了したバグ数の遷移を MRTG などでグラフ化するために、未終了、終了バグ数をテキストで返すアクションがあります。
test というプロジェクトID のプロジェクトがあるとき、 http://www.example.net/kagemai/guest.cgi?project=test&action=mrtg&t=2 のように、action として 'mrtg' を指定すると、text/plain 形式で、１行目に未終了のバグ数、 ２行目に終了したバグ数を返します。
MRTG での設定については、配布ファイル内の mrtg/mrtg.cfg を参考にしてください。 例えば、 このようなグラフが作成できます。
影舞は１つのインストールを複数の BTS として利用できます。
まず、Webサーバで公開可能なディレクトリを作成し、 guest.cgi, user.cgi, admin.cgi をコピーします。 また、必要に応じて kagemai.css や wallpaper.gif もコピーします。
$ 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
次に、guest.cgi 中の config_file を適切に変更します。
$ vi guest.cgi $ grep 'config_file' guest.cgi config_file = '/home/fukuoka/public_html/my_bts/kagemai.conf'
admin.cgi にアクセスし、"全体の設定"で、project_dir を変更します。 これで、もとの BTS とは別に利用することが可能になります。