Saturday, December 04, 2010

Bugtracking using Trac

This documentation is aimed at version 0.12

http://trac.edgewall.org

This documentation heavily based on the official documentation, so if you are unsure about something address it:
http://trac.edgewall.org/wiki/TracInstall

A. Prerequisites:

1. Database

I will use a MySQL database, but you could also use PostgreSQL or a local DB file (through Sqlite). So first you install the Server, if do not have one, and create the database according to the documentation, that I reproduce here.
#---
yum -y install \
mysql-server \
mysql \
MySQL-python
#---

I need "root" access for the following steps. (If have some "root" related problems please address to my corresponding post.)
http://gka-linux.blogspot.com/2010/03/mysql-root-password-reset.html

1.2. Start the server (if necessary):
#---
service mysqld restart
chkconfig --level 345 mysqld on
#---

1.3. Get "root" MySQL shell:
#---
## skip this part if you already have a working MySQL server
## mysql_secure_installation
mysql -u root -p
#---

1.4. Create the database (on the shell):
CREATE DATABASE trac DEFAULT CHARACTER SET utf8 COLLATE utf8_bin;
USE trac;
GRANT ALL ON trac.* TO tracuser@localhost IDENTIFIED BY '<plain text root password for trac>';

NOTE: Your connection string will be (remember it): mysql://tracuser:<plain text root password for trac>@localhost/trac

2. Version Control System:

For this example Subversion (SVN) which I already documented here:
http://gka-linux.blogspot.com/2009/07/subversion-and-apache-with-pam.html
Or Git: 
http://gka-linux.blogspot.com/2011/03/git-server-on-centos-55.html

3. Apache

I assume that you already have an Apache server and want to put Trac along with other pages you may have.

3.1. Additional packages:
#---
yum -y install \
mod_fcgid \
mod_python \
mod_wsgi
#---

B. The Trac:

OBS.: For CentOS boxes, you need RPMForge repository (or else you are bound to the version 0.10):

#---
wget http://packages.sw.be/rpmforge-release/rpmforge-release-0.5.2-2.el5.rf.x86_64.rpm
rpm -ivh rpmforge-release-0.5.2-2.el5.rf.x86_64.rpm
#---

1. Installing things:

1.1. Fedora:
#---
yum -y install \
trac \
trac-git-plugin \
trac-mercurial-plugin \
trac-iniadmin-plugin \
trac-accountmanager-plugin \
trac-customfieldadmin-plugin \
trac-peerreview-plugin \
trac-privateticketsplugin \
trac-ticketdelete-plugin \
trac-spamfilter-plugin
#---

1.2. CentOS:
#---
yum -y install \
trac \
trac-git-plugin \
trac-mercurial-plugin \
trac-iniadmin-plugin \
trac-peerreview-plugin \
trac-ticketdelete-plugin \
trac-spamfilter-plugin
#---

1.2.1 MySQL-python:

Because CentOS comes with MySql-python 1.2.1 (and this version does NOT work with Trac) you need to upgrade this manually:

#---
wget http://dev.centos.org/centos/5/testing/x86_64/RPMS/MySQL-python-1.2.2-3.el5s2.x86_64.rpm
rpm -Uvh MySQL-python-1.2.2-3.el5s2.x86_64.rpm
#---


2. Start the setup process:
#---
PRJ_NAME="<project name>"
PRJ_DIR=`echo $PRJ_NAME | tr [A-Z] [a-z] | sed -e "s/[^[:alnum:]]/\./g"`
DB_CONN="mysql://tracuser:<plain text root password for trac>@localhost/trac"
#DB_CONN="sqlite:db/trac.db"
REPOS_TYPE="git" # could be one of: "git", "mercurie" or "svn"
REPOS_DIR="/var/lib/git/${PRJ_NAME}.git"
TRAC_DIR="/var/local/trac"
TRAC_PRJS_DIR="${TRAC_DIR}/projects"
TRAC_PRJ_DIR="${TRAC_PRJS_DIR}/${PRJ_DIR}"
mkdir -p ${TRAC_PRJ_DIR}
trac-admin ${TRAC_PRJ_DIR} initenv "${PRJ_NAME}" "${DB_CONN}" "${REPOS_TYPE}" "${REPOS_DIR}"
#---

NOTE: If something goes wrong and you want to do it again just remove the directory (but be aware that the Trac content will be lost):
#---
rm -rf ${TRAC_DIR}
#---

2.1. CentOS:
Currently there is an open issue with GitPlugin and Trac working together on CentOS:
http://trac-hacks.org/ticket/3757
http://trac-hacks.org/ticket/8102

2.2. Git Repository setup:
#---
cat >> ${TRAC_PRJ_DIR}/conf/trac.ini << __END__
[git]
cached_repository = false
git_bin = /usr/bin/git
persistent_cache = false
shortrev_len = 7

[components]
tracext.git.* = enabled
__END__
#---



3. Setting up the Apache server:

I prefer this more complicated option because the odds are that you do not need yet another server running. Another assumption is that you will have several projects that also need separated tracking "spaces". For instance, you may start using technology "X" and latter on decide to migrate everything to technology "Y", so you probably do not want to mix bugs from "X" with "Y". This is, of course, obvious if you have software factory.

3.1. Create Web content (per project):

#---
TMP_DIR=`mktemp -d`
rm -rf ${TMP_DIR}
trac-admin ${TRAC_PRJ_DIR} deploy ${TMP_DIR}
mv ${TMP_DIR}/* ${TRAC_PRJ_DIR}
rm -rf ${TMP_DIR}
#---

3.2. Global configuration file (/etc/httpd/conf.d/trac.conf):
#---
cat > /etc/httpd/conf.d/trac.conf << __END__
#Global environment for Trac's CGI
<LocationMatch /cgi-bin/trac\.f?cgi>
SetEnv TRAC_ENV_PARENT_DIR "${TRAC_PRJS_DIR}"
</LocationMatch>
#Special environment for Trac's FastCGI CGI
<IfModule mod_fastcgi.c>
<LocationMatch /cgi-bin/trac\.fcgi>
FCGIDDefaultInitEnv TRAC_ENV_PARENT_DIR ${TRAC_PRJS_DIR}
</LocationMatch>
</IfModule>
#Python environment
<IfModule mod_python.c>
<LocationMatch "/trac/[^/]+/cgi-bin/trac.cgi>
SetHandler mod_python
PythonHandler trac.web.modpython_frontend
PythonOption TracEnvParentDir ${TRAC_PRJS_DIR}
</LocationMatch>
</IfModule>
##
# Authentication @ ${TRAC_DIR}/trac.htpasswd
# To add a new user:
# htpasswd ${TRAC_DIR}/trac.htpasswd <username>
#
##
<LocationMatch "/trac/[^/]+/login">
AuthType Basic
AuthName "Trac"
AuthUserFile ${TRAC_DIR}/trac.htpasswd
Require valid-user
</LocationMatch>
__END__
#---

3.3. Project specific configuration file (/etc/httpd/conf.d/trac-"<project name>".conf):
#---
cat > /etc/httpd/conf.d/trac-${PRJ_DIR}.conf << __END__
### Regular CGI
#ScriptAlias /trac/${PRJ_DIR} ${TRAC_PRJ_DIR}/cgi-bin/trac.cgi
### Fast CGI (default)
ScriptAlias /trac/${PRJ_DIR} ${TRAC_PRJ_DIR}/cgi-bin/trac.fcgi
__END__
#---

3.4. Authentication (via password file):

3.4.1. Creating the file AND admin user (JUST this ONE time):
#---
htpasswd -c ${TRAC_DIR}/trac.htpasswd admin
#---

3.4.2. Creating a regular user (notice the lack of '-c' parameter):
#---
htpasswd ${TRAC_DIR}/trac.htpasswd <username>
#---

3.4.3. Or use a generic safe single line:
#---
PASSFILE="${TRAC_DIR}/trac.htpasswd"
htpasswd `([[ -f ${PASSFILE} ]] && echo "" || echo "-c")` ${PASSFILE} admin
#---

#---
htpasswd `([[ -f ${PASSFILE} ]] && echo "" || echo "-c")` ${PASSFILE} <username>
#---

3.4.4. Check it out:
#---
cat ${PASSFILE}
#---

3.5. Security and SElinux:

3.5.1. SElinux and Trac:
#---
echo /usr/bin/chcon -R -v -t httpd_t \'${TRAC_DIR}\' | bash
#---

3.5.2. SElinux and Repository:
#---
echo /usr/bin/chcon -R -v -t httpd_t \'${REPOS_DIR}\' | bash
#---

4. Access and test:

#---
service httpd restart
firefox "http://localhost/trac/${PRJ_DIR}"
#---

C. Important files and directories:

1. Content:
/var/local/trac

2. Setup:
/var/local/trac/projects/<your project>/conf/trac.ini

3. Apache config:
3.1. General setup:
/etc/httpd/conf.d/trac.conf
3.2. Your project:
/etc/httpd/conf.d/trac-<your project>.conf

4. Logging:
/var/local/trac/projects/<your project>/log/