Trac構築メモ : 紹介マニア

Trac はソフトウェア開発プロジェクトのための要件管理システム(Issue Tracking System)です。

Python で開発されており Subversionを始めとしたあ各種SCMツールに対応しています。

ここでは自分が Trac を構築する時に必要な事項をメモしています。

インストール(バージョン0.11)
プロジェクト環境を作成
ユーザの作成
CGIの設定
initenv 時のデフォルトを変更
Mercurial に対応させる
- Mercurial pluginのインストール
- hookの設定
よくありそうなトラブルへの対処方法
- パーミッション
- 文字化け関連
Trac バージョン 0.12
更新履歴

インストール(バージョン0.11)

easy_install を利用してインストールするのが簡単です。

Trac の最新版は Genshi に依存していますが、 easy_install でインストールすれば依存性も解決してくれます。

Pygments と docutils もインストールしておくと良いでしょう。

インストール時 easy_installに egg を展開する「-Z」オプションを付与しておいてください。また既存ライブラリが更新されるように「-U」オプションも付与しておくと良いでしょう。

日本語化されたファイルを直接インストールします。日本語化された物に関しては http://www.i-act.co.jp/project/products/products.html を参照してください。

日本語化された物をインストールする場合はオリジナルの物をインストールしていない状態でインストールしてください。一部ファイルが正常に上書きされない場合があります。

sudo easy_install -UZ Pygments
sudo easy_install -UZ docutils
sudo easy_install -UZ http://www.i-act.co.jp/project/products/downloads/Trac-0.11.5.ja1.zip

プロジェクト環境を作成

プロジェクト環境の作成には trac-admin コマンドを利用します。 trac-admin コマンドが動作する事を確認します。

trac-admin --version
trac-admin --help

Mac OS X にデフォルトインストールされているPython 以外を利用していると以下のようなエラーがでるかもしれません。

LookupError: unknown encoding: X-MAC-JAPANESE

Python 2.6.1 の場合は以下を修正します。

sudo vi /Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/Trac-0.11.5.ja1-py2.6.egg/trac/util/text.py

の 59 行目を修正。

#return unicode(text, charset, 'replace')
return unicode(text, 'utf-8', 'replace')
# utf-8 がまずい場合は ascii にしてください

環境を初期化します。

trac-admin /path/to/myproject initenv

設定ファイルを修正します。

動作の確認をします。tracdを利用すると簡単です。

tracd --port 8080 /path/to/myproject

起動したら http://localhost:8080/trac にアクセスすると動作確認ができます。

このまま tracd を利用しても問題ないですが、後でApache経由での動作設定もしてみます。

ユーザの作成

管理者ユーザを作成します。今回はhtpasswd を利用してパスワード管理をします。pluginを利用すればLDAPで管理することも可能です。

htpasswd -c /path/to/myproject/trac.htpasswd admin
trac-admin /path/to/myproject permission add admin TRAC_ADMIN

全てをコマンドラインで登録するとユーザ増加時に作業できる要員が減ってしまうので AccountManager プラグインをインストールしてWeb画面から会員登録できるようにします。

sudo easy_install -UZ http://trac-hacks.org/svn/accountmanagerplugin/0.11/

/path/to/myproject/conf/trac.ini に以下を追加します。

[account-manager]
password_file = /path/to/myproject/trac.htpasswd
password_format = htpasswd
password_store = HtPasswdStore

[components]
acct_mgr.admin.accountmanageradminpage = enabled
acct_mgr.api.accountmanager = enabled
acct_mgr.htfile.abstractpasswordfilestore = enabled
acct_mgr.htfile.htpasswdstore = enabled
acct_mgr.web_ui.accountmodule = enabled
acct_mgr.web_ui.loginmodule = enabled
acct_mgr.web_ui.registrationmodule = enabled
trac.web.auth.loginmodule = disabled
webadmin.* = enabled

上記設定は比較的閉じられた環境向けです。この設定の場合 BASIC認証ダイアログでなくて通常ログイン画面からログインできるようになり、管理権限が付与されていると管理ツールが利用できます。

「acct_mgr.web_ui.registrationmodule = enabled」にしておくとWeb画面から会員登録ができます。

利用環境によってはアカウントの作成をしたら acct_mgr.web_ui.registrationmodule を disabled にしとく方が良いかもしれません。

trac.ini に他者からの書き込み権限を付与しておかないとApacheの設定によってはWeb画面から更新できませんのでパーミッションを以下のように変更する必要があるかもしれません。

chmod 757 /path/to/myproject
chmod 757 /path/to/myproject/conf
chmod 646 /path/to/myproject/conf/trac.ini

設定に関してはセキュリティ面をもっと考慮する必要があるかもしれません。

CGIの設定

Apache経由で参照する場合いろいろな方法がありますがとりあえず CGI で設定してみます。trac.cgi を利用します。

どこにあるか不明な場合は http://trac.edgewall.org/browser/trunk/cgi-bin/trac.cgi とかから直接取得しても問題ないです。

TRAC_ENV の設定が必要です。hg を利用する場合は HGENCODING も設定しておくと文字化けが防げます。

とりあえずはtrac.cgiを修正することで対応。

try:
  import os
  os.environ['TRAC_ENV'] = "/path/to/myproject"
  os.environ['HGENCODING'] = "UTF-8"
  from trac.web import cgi_frontend
  cgi_frontend.run()

を設定します。

起動させてみてください。

動作しないDB のパーミッションを変更する必要があるでしょう。

chmod 757 /path/to/myproject/db
chmod 646 /path/to/myproject/db/trac.db

この設定でだいたい動作するはずです。

initenv 時のデフォルトを変更

複数のプロジェクトを作成する場合は initenv 時のデフォルトを変更したい場合があります。

DB内の値に関するデフォルトの設定は db_default.py に記述されています。

場所が不明な場合は以下のコマンドで探すことができます。

mdfind db_default.py

ちなみに Mac OS 10.5 に Python 2.6 をインストールしていると以下の場所になります。

/Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/Trac-0.11.5.ja1-py2.6.egg/trac/db_default.py

中身を見ると修正点がわかります。

直接変更してしまっても良いですが、initenv した後 trac-admin コマンドを利用して更新した方が汎用的です。

trac.ini のデフォルトの値は inherit オプションを利用します。あらかじめ雛形となる trac.iniを作成しておく必要があります。

trac-admin /path/to/myproject initenv --inherit=/path/to/trac.ini

多くのプロジェクトを作成する場合はシェルスクリプト等を作成しておくと良いでしょう。

以下何かの参考用にスクリプトを置いておきます。

日本語にしている部分はsf.jp等のチケット部分を参考にしていますが、わたしが実際に利用している物とは異なることをご了承ください。

#!/bin/zsh

echo "start make trac"

project=$1

if [ -z $project ];then
   echo "empty!"
   exit
fi

pathto=/path/to/trac/$project

if [ -e $pathto ];then
   echo "exist!"
   exit
fi

# プロジェクト作成
mkdir $pathto
trac-admin $pathto initenv --inherit=/path/to/etc/trac.ini "${project} project" "sqlite:db/trac.db" "hg" "/path/to/hg/${project}"
chmod 757 $pathto
chmod 757 $pathto/conf
chmod 757 $pathto/db
chmod 646 $pathto/db/trac.db
chmod 646 $pathto/conf/trac.ini

# 管理者権限
trac-admin $pathto permission add admin trac_admin

# コンポーネント
trac-admin $pathto component rename component1 view
trac-admin $pathto component chown view admin
trac-admin $pathto component rename component2 controller
trac-admin $pathto component chown controller admin
trac-admin $pathto component add model admin

# マイルストーン
trac-admin $pathto milestone rename milestone1 release1
trac-admin $pathto milestone due 0.01 $(date -v+1m +%y-%m-%d)
trac-admin $pathto milestone remove milestone2
trac-admin $pathto milestone remove milestone3
trac-admin $pathto milestone remove milestone4

# 優先度
trac-admin $pathto priority change blocker p1
trac-admin $pathto priority change critical p2
trac-admin $pathto priority change major p3
trac-admin $pathto priority change minor p4
trac-admin $pathto priority change trivial p5

# 解決方法
trac-admin $pathto resolution change fixed 修正済み
trac-admin $pathto resolution change invalid 不正
trac-admin $pathto resolution change wontfix 直さない
trac-admin $pathto resolution change duplicate 重複
trac-admin $pathto resolution change worksforme 動いてるけど？

# 重要度

# チケット分類
trac-admin $pathto ticket_type change defect 障害
trac-admin $pathto ticket_type change enhancement 機能追加
trac-admin $pathto ticket_type change task やるべき事

# バージョン
trac-admin $pathto version remove 2.0
trac-admin $pathto version remove 1.0

echo "end make trac"

このスクリプトはあくまで参考に作成した物です。trac-admin の helpを参照して自分でカスタマイズすることをおすすめします。

Mercurial に対応させる

Mercurialその物の説明は割愛します。

Mercurial pluginのインストール

http://trac.edgewall.org/wiki/TracMercurial を参照すると良いです。

Mercurial 1.3.1に対応しています。

sudo easy_install -UZ http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin-0.11

easy_install で上手くインストールできない場合はローカルにチェックアウトしてインストールしてください。

svn co http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin-0.11
cd mercurial-plugin-0.11
sudo python setup.py install

trac.iniを以下のように編集します。

[trac]
repository_type = hg

[components]
tracext.hg.* = enabled

[hg]
show_rev = yes
node_format = short

hookの設定

hookを設定するとコミットした時に一定の動作をさせることができます。

Trac に付属している trac-post-commit-hook スクリプトを利用すれば簡単です。

詳細は http://d.hatena.ne.jp/dayflower/20080318/1205819818 を参照するのが良いです。

環境変数「PYTHON_EGG_CACHE」が正常に取れないとエラーになる場合があります。

if not 'PYTHON_EGG_CACHE' in os.environ:
         os.environ['PYTHON_EGG_CACHE'] = trac_env + '/eggs'

をload_moduleする直前あたり位置に挿入するとエラーにならないでしょう。

よくありそうなトラブルへの対処方法

一般的なトラブルへの対処方法

パーミッション

プロジェクトを作成した位置によってはパーミッションを変更しないと動作しないかもしれません。

以下のようにパーミッションを設定すればだいたい動作するでしょう。

chmod 757 /path/to/myproject
chmod 757 /path/to/myproject/conf
chmod 757 /path/to/myproject/db
chmod 646 /path/to/myproject/db/trac.db
chmod 646 /path/to/myproject/conf/trac.ini

動作しない場合だけ変更してみてください。

文字化け関連

ソースブラウザとかが文字化けする場合は以下を実施します。

文字コード判定用に Universal Encoding Detector(chardet)をインストールします。

http://chardet.feedparser.org/

sudo easy_install -UZ chardet

あとは http://blog.livedoor.jp/yamamb/archives/50613027.html にあるパッチをあてます。

Trac バージョン 0.12

Trac 0.12 はこのドキュメントを作成している時点は開発版です。

最新の機能を調査する目的で記述しています。

インストール(バージョン0.12)

easy_install を利用して開発版をインストールすれば利用することが可能です。

この文書はあくまで開発版のインストールの例を示しているだけで、インストールを推奨する物ではありません。

Trac 0.12 は以下の点が 0.11 と異なります。

国際化されていますので日本語ファイルなどを別途用意する必要はありません
一つのプロジェクトで複数のレポジトリを管理することができます
Mercurial (hg) にデフォルトで対応しています
Python 2.4以上でしか動作しません(Python 2.3 はサポートしていません)
SQLite v3.x以上でしか動作しません(SQLite v2.x はサポートしていません)
古いスタイルのWikiマクロが動作しません

以上の注意を確認の上、本当に理解できる人だけインストールしてみるのも良いでしょう。

ここでは multirepos をインストールしています。

sudo easy_install -UZ pygments
sudo easy_install -UZ docutils
sudo easy_install -UZ http://svn.edgewall.org/repos/genshi/trunk/
sudo easy_install -UZ http://svn.edgewall.com/repos/trac/sandbox/multirepos

0.11 の設定の知識で動作しますが、plugin類は 0.12 に対応しているものをインストールする必要があります。

バージョンアップ(0.11 から 0.12)

バージョンアップする場合必ず DB をバックアップしてください。

バージョンアップはインストールと同じ手順です。バージョンアップした後 DB を以下のコマンドで形式を変換する必要があります。

変換すると 0.11 では動作しなくなりますのでご注意ください。

trac-admin /path/to/myproject upgrade

場合によっては以下のエラーが発生する場合があります。

LookupError: unknown encoding: x-mac-japanese

この場合は、以下を修正します。

sudo vi /Library/Frameworks/Python.framework/Versions/2.6/lib/python2.6/site-packages/Trac-0.12dev_r0-py2.6.egg/trac/util/text.py

の 68 行目を修正。

#return unicode(text, charset, 'replace')
return unicode(text, 'utf-8', 'replace')

これは Mac OS X上でのAppleのパッチが当っていないPythonで発生する問題ですので独自にPythonをビルドしていないと発生しないでしょう。

このままだとWikiのhelpの内容が古いので内容を更新する場合は以下です。場合によっては既存のWikiの内容が壊れる可能性がありますのでご注意ください。

trac-admin /path/to/myproject wiki upgrade

バージョンアップするとソースコードレポジトリとの同期に異常が発生する場合がありますので同期を実施します。

trac-admin /path/to/myproject resync

バージョンアップが上手くいかなかった場合は 0.12 を削除して 0.11 をインストールし DB をもとに戻してください。

バージョンアップの場合 plugin が上書きされない場合があります。各種 plugin もバージョンを確認しておいてください。

上手く動作しているなら無理にバージョンアップしない方が無難です。

sudo easy_install -UZ http://svn.edgewall.com/repos/trac/sandbox/mercurial-plugin-0.12

複数レポジトリ設定

複数レポジトリを扱うには以下のように trac.ini に設定します。

「repository_type」にはデフォルトでは「hg」、「svn」、「svnfs」が選択できます。適切な物を設定してください。

[trac]
repository_dir = /path/to/hgrepo
repository_type = hg

[repositories]
reponame_a.dir = /path/to/anotherhgrepo
reponame_b.dir = /path/to/anothersvnrepo
reponame_b.type = svnfs

レポジトリと同期します。

trac-admin /path/to/trac repository resync "(default)"
trac-admin /path/to/trac repository resync reponame_a
trac-admin /path/to/trac repository resync reponame_b

レポジトリ毎に Trac プロジェクトを構築していた場合に複数レポジトリにおいて課題になるのは既存のチケットの統合をどう実施するかです。

この課題に関しては現在検討中ですが、チケットが少ないようであれば手作業で統合するのが無難です。

hookの設定(Mercurial)

バージョンアップすることで hook スクリプトを変更する必要があります。

各レポジトリに対応しています。

# -*- encoding: utf-8 -*-
# see http://d.hatena.ne.jp/dayflower/20080318/1205819818

trac_env    = '/path/to/trac'
repo_name   = 'reponame_a'
# see http://trac.edgewall.org/browser/sandbox/multirepos/contrib/trac-post-commit-hook?rev=7542
hook_script = '/path/to/bin/trac-post-commit-hook'

# style:: 'short', 'long', or 'number'
changeset_id_style = 'number'

import os

def invoke_trac_hook(trac_env, rev):
   def _make_smart_rev(trac_env, rev):
       if changeset_id_style == 'long':
           return rev
       else:
           import trac.env
           env = trac.env.open_environment(trac_env)
           # instance of mercurial.hg.repository
           repo = env.get_repository(repo_name).repo
           ctx = repo.changectx(rev)
           if changeset_id_style == 'short':
               import mercurial.node
               return mercurial.node.short(ctx.node())
           else:   # 'number'
               return str(ctx.rev())

   smart_rev = _make_smart_rev(trac_env, rev)

   f = open(hook_script, 'r')
   try:
       import imp
       ext = os.path.splitext(hook_script)[1]
       #print os.path.splitext(hook_script)
       if not 'PYTHON_EGG_CACHE' in os.environ:
           os.environ['PYTHON_EGG_CACHE'] = trac_env + '/eggs'
       m = imp.load_module('trac_hook', f, f.name, (ext, f.mode, imp.PY_SOURCE))
       m.CommitHook(project=trac_env, rev=smart_rev, reponame=repo_name)
   finally:
       f.close()

invoke_trac_hook(trac_env, os.environ['HG_NODE'])