INSTALL

====== インストール方法 ======

Starbug1は、SQLite3、cgic、gettext、iconvを使用しています。 コンパイルするためには、gettext、sqlite3、cgicが必要です。(FreeBSDでコンパイルするには、それらに加えてlibiconvが必要になります。)

===== 基本ソフトウェアのインストール =====

gcc, gettext, rsyncをインストールして下さい。
Ubuntuの場合は、以下のコマンドを実行して必要なソフトウェアをインストールできます。

<code>
  sudo apt-get install build-essential gettext rsync libjson-perl liblocale-po-perl
</code>

====== スタティック版 インストール方法 ======

===== Starbug1のコンパイル =====

ソースを取得する。

Downloadから最新ソースを取得する。https://sourceforge.jp/projects/starbug1/
==== コンパイル ====

取得したソースを展開しコンパイルします。

<code>
$ tar zxf starbug1-x.x.x.tar.gz
$ cd starbug1
$ make INITIAL_LOCALE=ja_JP static
</code>
      
※Starbug1をコンパイルする場合は、gnuのmakeが必要です。OSがFreeBSDなどの場合で、makeがgnuのmakeでない場合は、gmakeを使用してコンパイルしてください。
dist/starbug1 ディレクトリに、webアプリ一式が生成されます。


Starbug1 1.3以降の場合、多言語で使用することができます。(1.3.01では、日本語、英語、簡体中国語に対応しています)

=== 英語版としてコンパイルする場合 ===

<code>
$ tar zxf starbug1-x.x.x.tar.gz
$ cd starbug1
$ make INITIAL_LOCALE=en_US webapp
</code>

=== 簡体中国語版としてコンパイルする場合 ===

<code>
$ tar zxf starbug1-x.x.x.tar.gz
$ cd starbug1
$ make INITIAL_LOCALE=zh_CN webapp
</code>

==== Starbug1の配置 ====

Webサーバ(動作確認しているのはapache)のDocumentRoot配下に dist/starbug1 ディレクトリを配置します。下の例は、/var/www/ をDocumentRootとした場合です。

<code>
$ su
# cp -r dist/starbug1 /var/www/
</code>


(インストールディレクトリ)/starbug1 配下をcgi実行ユーザの権限に変更します。

<code>
# cd /var/www
# chown -R www-data:www-data starbug1
</code>      

==== Webサーバに合わせた設定ファイルを適切に編集します。(以下はapache用設定です) ====

dot.htaccessを.htaccessにファイル名変更して、 各設定を適切に行なってください。 Apache以外のWebサーバで運用する場合は、それぞれのWebサーバに合わせて同様の設定を行なってください。

<code sh>
$ mv dot.htaccess .htaccess
$ cat .htaccess
</code>

<code apache>
# エラーページの指定
ErrorDocument 500 /starbug1/error.html
# CGIの実行許可
AddHandler cgi-script cgi
Options +ExecCGI
# 初期ページの設定
DirectoryIndex index.cgi

# 一般ユーザの認証についての設定
<Files index.cgi>
    AuthName      "authentication for guest user."
    AuthType      Basic
    AuthUserFile  /etc/starbug1/.guest-passwd
    Require       valid-user
</Files>

# 管理ユーザの認証についての設定
<Files admin.cgi>
    AuthName      "authentication for administrator user."
    AuthType      Basic
    AuthUserFile  /etc/starbug1/.admin-passwd
    Require       valid-user
</Files>
# 隠すファイルやディレクトリ
<FilesMatch ".*">
  deny from all
</FilesMatch>
# 見せるファイル
<FilesMatch "(^$|\.cgi$|\.jpg$|\.png$|\.gif$|\.css$|\.js$)">
  allow from all
</FilesMatch>
</code>      

  * エラーページの指定

URLを適切に指定してください。アプリのフォルダ名(starbug1)を変更した場合は、エラーページの指定のURLを変更してください。

  * CGIの実行許可

不要であれば、コメントアウトしてください。

  * デフォルトページ(welcomeページ)

不要であれば、コメントアウトしてください。

  * Basic認証

Basic認証を使用する場合、htpasswdなどでパスワードファイルへのユーザの登録を行なってください。 一般ユーザと管理ユーザの設定を別々に行なう場合は、両方を正しく設定してください。不要であればコメントアウトしてください。 httpd.confを編集できる場合は、同等の設定を、httpd.confで行なう方が望ましいです。


http://www.example.com/starbug1/index.cgi にアクセスします。(www.example.comはインストールしたサーバ名に変更してください)

トップ画面が表示されれば、インストール成功です。

===== hook機能について =====

==== 概要 ====

hook機能は、チケットの登録・返信完了時に外部プログラムを呼び出す機能です。 hookとして、外部プログラムを設定すると、チケット登録・返信完了時に外部プログラムを実行させることが可能になります。 また、hookの呼び出しインターフェースが外部プログラムを呼び出す形式であるため、サーバ上の実行可能ファイルであれば、言語は問いません。 アイデアとしては、以下のようなことが実現できます。

=== メール通知 ===

登録された内容を、メーリングリストへメール送信するようスクリプトをhookに登録する。

=== 登録ログ保存 ===

登録された内容を、ファイルに保存するようスクリプトをhookに登録する。

=== メッセンジャー通知 ===

登録された内容を、メッセンジャーに自動投稿するスクリプトをhookに登録する。

=== 再ビルド ===

登録された内容から、プロジェクトのソースを自動ビルドするスクリプトをhookに登録する。

アイデア次第では、面白いことができるかもしれません。通常のインストールを行なうと、メール送信用の perl スクリプトのサンプルがscriptディレクトリに配置されます。(メール送信を行なうには、設定が必要です。)

==== hook機能の仕様 ====

Starbug1は、サーバ上でチケットの登録・返信完了時に以下の動作を行ないます。
${Starbug1のインストールディレクトリ}/scriptディレクトリ内にある、hook_ で始まるファイル名の実行ファイルを検索します。実行ファイルが見付かった場合、送信内容をjson形式に変換し、環境変数${STARBUG1_CONTENT}に設定した状態で、実行ファイルを実行します。実行ファイルが複数存在した場合は、順に実行ファイルを実行します。
チケット登録・返信完了のメッセージと一緒に、スクリプトの実行結果を表示します。
hook機能に登録された外部スクリプトでエラーが発生した場合は、「登録が完了しました。」のメッセージの後に、スクリプトの実行が失敗した旨のメッセージが表示されます。

環境変数${STARBUG1_CONTENT}に設定されるjsonは以下のような形式になります。(ただし、見易いように整形してあります。) 各言語のjsonとオブジェクトの変換ライブラリで変換すれば、簡単に投稿内容を取得できます。
<code javascript>
{
  project: { name: "テストサンプル プロジェクト"},
  ticket: {
    id: 2,
    url: "http://popnuts.ddo.jp/starbug1/index.cgi/ticket/2",
    fields: [
      { name: "件名",     value: "誰でも投稿できるようになっていた件について" },
      { name: "投稿者",   value: "smeghead" },
      { name: "状態",     value: "受付済" },
      { name: "カテゴリ", value: "画面 " },
      { name: "優先度",   value: "高" },
      { name: "詳細",     value: "テスト詳細2" },
      { name: "再現手順", value: "テスト再現手順2" },
      { name: "コメント", value: "" }
    ]
  }
}
</code>
      
==== 添付のメール送信スクリプトの設定方法 ====

== perlモジュールのインストール ==

添付のサンプルメール送信スクリプトは、HTTP::Dateと、JSON:Syckを利用しています。あらかじめ、cpanなどでインストールしておいてください。

== メール送信スクリプトの設定 ==

添付のメール送信スクリプトの設定には、多少perlの知識が必要となります。
Starbug1に添付されているメール送信スクリプトの設定方法を説明します。 ${Starbug1のインストールディレクトリ}/scriptディレクトリに、sample.hook_sendmail.pl が存在します。 以下のコマンドで、メール送信スクリプトをhook_で始まるファイル名に変更します。

<code sh>
# cd ${Starbug1のインストールディレクトリ}/script
# mv sample.hook_sendmail.pl hook_sendmail.pl
</code>

スクリプトの一行目を、perlのpathに変更します。

<code sh>
#!/usr/local/bin/perl
</code>
      
メール送信のための情報を設定します。$options というhashに対して設定を行ないます。 赤文字の部分がカスタマイズ部分です。
<code perl>
my $options = {
  #使用するSMTPホスト名
  smtp_host => 'localhost',
  #使用するSMTPポート番号
  smtp_port => 25,
  #送信するメールのFROMを指定してください。
  from => 'project-admin@example.com',
  #メールの送信先を指定してください。通知したいメーリングリストのアドレスなど。
  to => 'project-ml@example.com'
};
</code>

設定後、シンタックスエラーが無いかをチェックします。cオプションを指定して実行してください。

<code>
# perl -c hook_sendmail.pl
</code>
      
注意: ここで、モジュールが見付からないというエラーが発生した場合は、不足しているライブラリをインストールしてください。
以上の設定を行なった後、チケットの登録・返信を行なって、動作確認を行なってください。

===== バックアップの方法 =====

Starbug1で定期的にバックアップを行ないたい場合は、${インストールディレクトリ}/db/*.db をバックアップしてください。 *.dbは、ただのSQLite3のデータベースファイルです。
例えばcronに登録する場合は以下のようにcrontab -e で設定すれば、バックアップできます。
<code>
# /var/www/starbug1 にインストールされたStarbug1のデータベースを、
# gzipで圧縮して /var/backup 以下に保存する場合です。
0 1 * * * tar zcf /var/backup/starbug1backup_$(date +%Y%m%d).tar.gz /var/www/starbug1/db
</code>
      

===== 設定情報をエクスポートする機能について =====

==== 概要 ====

設定情報をエクスポートすることができます。 設定情報とは、プロジェクトに設定された項目、項目の選択肢などの情報とユーザ用スタイルシートです。 既に存在するプロジェクトから、設定情報を取得し、新しいプロジェクトに設定情報を移行することができます。

==== 既に存在するプロジェクトの設定データを保存する方法 ====

既に存在するプロジェクトの動作環境のサーバ上でコマンドを実行します。

<code sh>
# cd /somewhere/to/old/project
# cd script
# ./pickup_template
</code>
      
実行後、template ディレクトリが作成され、内部にテンプレートが作成されます。既にtemplateディレクトリが存在する場合、削除されますのでバックアップが必要な場合は先にバックアップしてください。
==== 保存した設定データを新しいプロジェクトに反映させる方法 ====

新しいプロジェクトをインストールします。正常にインストールが完了した状態で、保存してあったtemplateディレクトリを上書きします。

<code sh>
# cp -r /somewhere/to/old/project/template/* /somewhere/to/new/project/
</code>

その後、新しいプロジェクトのdbディレクトリの所有者をhttpサーバの実行ユーザに変更します。
<code sh>
# cd /somewhere/to/new/project/
# chown -R www-data:www-data db
</code>

以上で、新しいプロジェクトに古いプロジェクトの設定情報が反映されます。 新しいプロジェクトと古いプロジェクトのバージョンが違う場合は、正常に反映されない又は正常に動作しない可能性があります。

===== うまく動かない場合 =====

  * インストール完了したが、ブラウザで http://www.example.com/starbug1/ にアクセスするとエラーが発生し、Webサーバのエラーログに、「Premature end of script headers: index.cgi」のようなメッセージが出力される。

CGIを実行する権限があるか確認してください。以下のような簡単なperlのcgiスクリ プトをstarbug1ディレクトリに配置し実行権限を付加して動作するかどうか確認す ることで、CGI自体が有効になっているかどうかを確認できます。

<code perl>
#!/usr/bin/perl
print "Content-Type: text/plain;\n\nhello.";
</code>

Webサーバプロセスユーザが、starbug1ディレクトリに書き込み権限があるか確認し てください。データベースファイルを格納するために、Webサーバプロセスユーザが starbug1ディレクトリに書き込み可能となっている必要があります。