Trac Installation

From DreamHost
Revision as of 10:37, 2 August 2011 by Andrew F (Talk | contribs)

Jump to: navigation, search

This article describes how to install Trac, an integrated Wiki and Issue Tracker with support for Subversion. This instructions are based on the Unix account setup.

There are alternative instructions in this wiki in automated Trac installation and in several Trac installation scenarios. Since the latter was too crowded, this instructions were put here, in a separate page.


The instructions provided in this article or section require shell access unless otherwise stated.

You can use the PuTTY client on Windows, or SSH on UNIX and UNIX-like systems such as Linux or Mac OS X.
Your account must be configured for shell access in the Control Panel.
More information may be available on the article's talk page.


Prerequisites

easy_install Genshi
cd ${HOME}/soft
wget http://docutils.sourceforge.net/docutils-snapshot.tgz
tar xzvf docutils-snapshot.tgz
cd docutils
${RUN}/bin/python setup.py build
${RUN}/bin/python setup.py install
  • Install the SilverCity lexer for syntax highlighting
cd ${HOME}/soft
wget http://downloads.sourceforge.net/silvercity/SilverCity-0.9.7.tar.gz
tar xvzf SilverCity-0.9.7.tar.gz
cd SilverCity-0.9.7
${RUN}/bin/python setup.py build
${RUN}/bin/python setup.py install
  • You can also install the new style syntax highlighter: Pygments by simply:
easy_install Pygments

Download and install Trac

Now you can download and install Trac:

cd ${HOME}/soft
wget http://ftp.edgewall.com/pub/trac/trac-0.10.4.tar.gz
tar xvzf trac-0.10.4.tar.gz
cd trac-0.10.4
${RUN}/bin/python setup.py build
${RUN}/bin/python setup.py install

Install a few global plugins

WebAdmin

WebAdmin is a plugin which allows some administration to be done from the web interface (to install for trac 0.10.x you have to use the svn repository version, starting with 0.11 this plugin is no longer needed, since trac provides the functionality internally).

easy_install http://svn.edgewall.com/repos/trac/sandbox/webadmin

After you create a trac project environment, you'll have to:

  • give TRAC_ADMIN permission to at least one of the users (which will have the admin option available in the web).
  • enable the plugin the trac.ini.

AccountManager

AccountManager is a plugin which allows new users to register on their own using the site, and change their passwords if necessary. This also allows login via form, rather than the HTTP authentication.

easy_install http://trac-hacks.org/svn/accountmanagerplugin/0.10

After you create a trac project environment, you'll have to:

  • enable the plugin the trac.ini.

Trac Project Environment

For each Trac project (site) you want to create, you have to follow this instructions.

Environment variables

  • Create some environment variables to hold the names of stuff that will change from installation to installation and from user to user in order to automate the setup:
  • Suppose you will create a Trac Project named "My Trac Project". You'll have to name your trac environment with a short name, e.g: mytracproject.
  • You will be creating a subversion repository named, for instance, tracrepo.
  • Your subversion repository will be configured in domain svn.example.org, in the path /svntrac, like: http: //svn.example.org/svntrac (you fill in this info when you create the repository in the control panel).
  • Trac will be available from trac.example.org without any path after it, like: http: //trac.example.org
  • A user called administrator will be the trac administrator (with permission to do anything).
  • Note: somehow, it is not working OK if you set TRACPATH to anything but "/". It seems some of the code generates absolute paths.

Replace the following with your actual data and type in the shell:

# NOTE: These are EXAMPLE settings based on the assuptions above
SVNDOMAIN="svn.example.org"
SVNPATH="/svntrac"
SVNREPO="tracrepo"
SVNPRIV="${HOME}/svn"
TRACDOMAIN="trac.example.org"
TRACPATH="/"
TRACENV="mytracproject"
TRACNAME="My Trac Project"
TRACPRIV="${HOME}/data/trac"
TRACADMIN="administrator"

Create the trac project environment

  • Make sure that ${TRACPRIV}/${TRACENV} doesn't exist.
if [ -d ${TRACPRIV}/${TRACENV} -o -f ${TRACPRIV}/${TRACENV} ]
then
  echo ${TRACPRIV}/${TRACENV} already exists... moving it away:
  mv -v ${TRACPRIV}/${TRACENV} ${TRACPRIV}/${TRACENV}.BackUp
fi
echo creating trac environment "${TRACNAME}" in ${TRACPRIV}/${TRACENV}...
trac-admin  "${TRACPRIV}/${TRACENV}" initenv "${TRACNAME}" "sqlite:db/trac.db" "svn" "${SVNPRIV}/${SVNREPO}" "${RUN}/share/trac/templates"

This will create a new directory ${TRACPRIV}/${TRACENV} with a few subdirectories and a README and a VERSION files. This is your trac environment.

Modify default permissions

  • This is an example. Other than the first two commands, you should read TracPermissions and decide how you want to configure it in your installation. In fact, after doing the first two and enabling the WebAdmin plugin you can manage the permissions from the administration web pages.
# create a group "admin" by adding a user to it
trac-admin "${TRACPRIV}/${TRACENV}" permission add ${TRACADMIN} admin
# give the group "admin" root permissions (i.e. everything):
trac-admin "${TRACPRIV}/${TRACENV}" permission add admin TRAC_ADMIN

# don't let anonymous users write in the wiki or close tickets
trac-admin "${TRACPRIV}/${TRACENV}" permission remove anonymous WIKI_CREATE WIKI_MODIFY TICKET_MODIFY
# but allow them to append and modify properties of tickets
trac-admin "${TRACPRIV}/${TRACENV}" permission add anonymous TICKET_APPEND TICKET_CHGPROP
# and give the "write in the wiki" and "close ticket" permissions to authenticated users
trac-admin "${TRACPRIV}/${TRACENV}" permission add authenticated WIKI_CREATE WIKI_MODIFY

Configure the trac project environment

  • Edit your trac.ini (located in ${TRACPRIV}/${TRACENV}/conf/trac.ini):
    • First, let's configure the WebAdmin plugin and the Account Manager plugin, so that you can use your subversion authentication file as the trac authentication file, and also you are able to login and register with a web form:
cat >>${TRACPRIV}/${TRACENV}/conf/trac.ini <<EOF
[components]
; enable WebAdmin module
webadmin.* = enabled
; disable standard trac login module
trac.web.auth.loginmodule = disabled
; enable Account Manager login module (login via web form)
acct_mgr.web_ui.loginmodule = enabled
; store passwords in an htpasswd file
acct_mgr.htfile.htpasswdstore = enabled
; enable web registration of trac users
acct_mgr.web_ui.registrationmodule = enabled
; enable web interface to admin page
acct_mgr.admin.accountmanageradminpage = enabled

[account-manager]
; passwords are stored in an htpasswd file
password_store = HtPasswdStore
; the htpasswd file is the same as the one used by the subversion repository
password_file = ${SVNPRIV}/${SVNREPO}.passwd

EOF
  • Under the [header_logo] heading, change link = http: //example.org/ by the URL by which your trac instance will be available. This line should look like the output of this command:
echo "link = http://${TRACDOMAIN}${TRACPATH}"


Put the trac script in the web

You have to make a copy of the trac.fcgi script in the web directory where this trac environment will be hosted and you'll have to add a couple of lines to it in order to allow it to find the trac environment you just created:

mkdir -pv ${HOME}/www/${TRACDOMAIN}${TRACPATH}
cd ${HOME}/www/${TRACDOMAIN}${TRACPATH}

sed -e "s#^try:#import os\n\
os.environ['TRAC_ENV'] = \"${TRACPRIV}/${TRACENV}\"\n\
os.environ['TRAC_ENV_PARENT_DIR'] = \"${TRACPRIV}\"\n\n\n\
try:#" ${RUN}/share/trac/cgi-bin/trac.fcgi > trac.fcgi

chmod -v --reference=${RUN}/share/trac/cgi-bin/trac.fcgi trac.fcgi

Now, make trac.fcgi the default handler in this directory and make it handle every request for a non-existent file or directory:

cd ${HOME}/www/${TRACDOMAIN}${TRACPATH}
cat > .htaccess <<EOF
DirectoryIndex trac.fcgi

Options ExecCGI FollowSymLinks
<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteCond %{REQUEST_FILENAME} !-f
  RewriteCond %{REQUEST_FILENAME} !-d
  RewriteRule ^(.*)\$ trac.fcgi/\$1 [L]
</IfModule>
EOF

Pretty URLs (optional)

LOOKOUT this is systemwide setting for all the trac environments you create. That is, other trac sites may not work if they aren't configured with an .htaccess file like the one above.

You can optionally modify Trac so that the /trac.fcgi is not shown in the URLs generated by trac itself, if you want this, do the following :

sed -i.BackUp \
 -e "s#base_path = property(fget=lambda self: self.environ.get('SCRIPT_NAME', '')#base_path = property(fget=lambda self: os.path.dirname(self.environ.get('SCRIPT_NAME', ''))#" \
 ${PYLIBPKG}/trac/web/api.py

Further Instructions

These instructions may require that you have set environment variables as explained above.

Restart Trac

Since this configuration of Trac uses FastCGI (rather than CGI), simply reloading the page won't restart the process. In fact, if you change something in the code (like, e.g. enabling pretty URLs), the code won't simply run the next time you load a page, since the very nature of FastCGI is to avoid this for performance reasonce (hence the Fast in the name).

To force the server to load, you must modify the main script (or at least its last modification timestamp) so that the server knows its cache is invalid. Simply do the following:

touch ${HOME}/www/${TRACDOMAIN}${TRACPATH}/trac.fcgi

and the next time you load a page from this trac, it will reload the script.

Patching Trac to Spanish

As of Trac 0.10.x, there's no i18n support, so the translations are simply patches applied mainly to pages and scripts, so handle this with care. These instructions are for the Trac Spanish Translation, but others should be quite similar.

You must patch Trac before installing it, so, if you already have Trac installed, you'll have to patch and reinstall.

Note: there are no patches for point (sub)versions of trac, so the patches only apply to the stable branch of the Trac 0.10 subversion repository.

  • Checkout the head of the 0.10-stable branch:
mkdir -pve ${HOME}/soft/TracStuff
cd ${HOME}/soft/TracStuff
svn co https://svn.edgewall.com/repos/trac/branches/0.10-stable trac-0.10-stable
  • Checkout the corresponding Spanish translation:
cd ${HOME}/soft/TracStuff
svn co  https://trac-hacks.org/svn/tracspanishtranslation/0.10 trac-0.10-stable-es-patches
  • Now apply the patches
cd ${HOME}/soft/TracStuff/trac-0.10-stable
patch -p0 -f < ../trac-0.10-stable-es-patches/patchs/trac-spanish-python_utf-8.diff
patch -p0 -f < ../trac-0.10-stable-es-patches/patchs/trac-spanish-templates_utf-8.diff
  • Now you can build and install the patched (translated) trac
  • You should previously remove the old 'egg' file
rm -i ${PYLIBPKG}/trac-0.10.4-py2*.egg-info
cd ${HOME}/soft/TracStuff/trac-0.10-stable
${RUN}/bin/python setup.py build
${RUN}/bin/python setup.py install
  • Upgrade the database and wiki
trac-admin  "${TRACPRIV}/${TRACENV}" upgrade
trac-admin  "${TRACPRIV}/${TRACENV}" wiki upgrade
  • If you had enabled pretty URLs, then you have to do it again (since this installation ereased the modification you applied there.

Converting a wiki from MoinMoin to Trac

There's a small script called moin2trac which helps in converting a wiki site from MoinMoin to Trac.

  • Download and open the script
mkdir -pve ${HOME}/soft/TracStuff
cd ${HOME}/soft/TracStuff
# we're downloading an attachment from a ticket 'cause the version in the
# repository has unfixed bugs
wget -O mointotracscript.zip \
 'http://trac-hacks.org/attachment/ticket/1426/mointotracscript.zip?format=raw'
unzip mointotracscript.zip
  • Convert a MoinMoin site
# ${TRACPRIV} and ${TRACENV} environment variables must be [[#Environment variables|set as explained above]]
# CHANGE THIS!!
MOINDATAPAGES=<put here the absolute path of your MoinMoin site data pages directory>

cd ${HOME}/soft/TracStuff/mointotracscript
${RUN}/bin/python moin2trac.py ${MOINDATAPAGES} ${TRACPRIV}/${TRACENV}

Notes: