From DreamHost

If you do not want to go through this process, you can vote for Dreamhost to add Trac as a One-Click install in the future. To vote, click here.

This article describes how to install Trac, an integrated Wiki and Issue Tracker with support for Subversion. These instructions assume you will be doing this on a shared host (DreamHost) without the benefit of Debian packages. While Trac is a powerful collaborative tool, the limited resources available on entry-level DreamHost hosting accounts may prevent you from getting good performance and reliability.

There are Ruby on Rails clones of Trac, called Collaboa or Retrospectiva that might be easier to install. Collaboa currently does not include a wiki and lacks some of the style and features of Trac. It is worth looking into for an alternative to Trac. Installing Bugzilla on DreamHost is quite straighforward by comparison..

Easier Installation

Petar Marić has created the dreamy-trac open-source project dedicated to automatically installing and managing Trac on DreamHost shared hosting. It has more features and is way simpler to use than DreamTracInstall.

This guide aims to provide as much information as possible to troubleshoot Trac installations. For people who find this distracting there are some straight forward installation guides (though a little bit outdated) outside of the DreamHost wiki listed in external links below. For true hackers here is also a link to instructions on official Trac site.

Installation

Use the Easier Installation Instructions! Unless you feel like a true hacker, go back up and look at the Easier Installation Instructions if you do not to waste hours or days of your life.

Ease of Install: Really Difficult for versions prior to 0.11 (reported conflicts with library versions) and Average for 0.11 (requires modification to some packages).

For help on using the shell you can take a look at the UNIX commands and you can also get help on changing directories.

If you want to save the output for debugging and support then you can look at the Redirection Symbol.

Installing Required Tools

Required that you do the Environment Setup for configuring the install paths for the packages.

Python

1. Python Installation Guide - 2.5.2 or better
2. Clearsilver Installation Guide - 0.10.5
   • Required only for 0.10.x versions
   • Requires modification before installation.

SQLite

1. SQLite Installation Guide - 3.3.4
2. PySQLite Installation Guide - 2.0.7

Subversion

1. SWIG Installation Guide 1.3.24 or above.
   • Use Recommended versions for your Subversion version.
   • Some server already have SWIG 1.3.24 instaled
2. Subversion Installation Guide - Use either 1.4.x or 1.5.x with python bindings.

Trac 0.10.x

Try natmaster's updated installation guide for installing 0.10.x.

Features

• InterTrac and InterWiki
• Expermential MySQL support
• Unicode Support

Trac 0.11

See the automated script for installing Trac version 0.11

Features

• Lots

Latest Version

Not Recommended for Production Sites

This will grab the development version of Trac, which will most likely be incomplete and thus filled with bugs which may halt the Trac site. Check the [1] page for the active and closed bugs. Should only be used if you want to debug the latest version to help the Trac development.

svn co http://svn.edgewall.com/repos/trac/trunk trac-latest
cd trac-latest
~/bin/python setup.py install
cp cgi-bin/trac.fcgi $HOME/share/trac/cgi-bin/

Configuration

To apply examples in this section replace {USER} with your shell username and {your.trac.environ} with the path to Trac environment.

Creating a Trac Environment

For each Trac site you want to create you need to run the Trac environment setup tool. When using trac-admin the path you specify must not exist or you will receive errors. If DreamHost's domain bot created a directory where you want to install Trac you will need to delete it. Then run the setup tool:

~/bin/trac-admin ~/{your.trac.environ} initenv

This will start an interactive script that will ask you some questions. Pressing enter accepts the default values.

• Project Name: This will appear at the top of the Trac site so enter what you want to see there.
• Database connection string: press Enter
• Path to repository: Specify the absolute path to your Subversion repository folder. e.g. /home/{USER}/svn/my project
• Templates directory: press Enter

If you need to make changes then you can do so by editing ~/{your.trac.environ}/conf/trac.ini

Setting up on your Domain

You need to do these steps for each Trac environment that you create. The steps are for FastCGI, but you can use for plain CGI if you remove the 'f' from the file names and uncomment some lines in the directions.

You can not run the CGI bash script from the command line. It will return errors if you do. You may run the bash script from the command line if you want to debug, but just ignore the 500 error that will show up and focus on the other errors.

Make sure you are in the directory of the public web site.

cd yourdomain.com

Creating the index file for FastCGI

nano index.fcgi

In the editor enter this text and carefully change {USER} and {your.trac.environ}:

#!/bin/bash
export TRAC_ENV="/home/{USER}/{your.trac.environ}"
 
# If you get 500 errors maybe you need to set/export the LD_LIBRARY_PATH,
# just uncomment the following lines and make sure it points to the same place
# you used before (Environment Setup).
# export LD_LIBRARY_PATH=/home/{USER}/lib/
# export PATH="/home/{USER}/bin:$PATH"
 
exec /home/{USER}/share/trac/cgi-bin/trac.fcgi

# unless you're using regular CGI in which case comment the above
# and uncomment the next line
# exec /home/{USER}/share/trac/cgi-bin/trac.cgi

Save and Close the file by pressing:

Ctrl+O
Ctrl+X

Change permissions on the bash file (index.fcgi for FastCGI and index.cgi for CGI)

chmod 755 index.fcgi

Edit the .htaccess file

nano .htaccess

Add the following. Warning: This may cause a 500 Server error and to solve just comment out these lines.

# This will cause all files ending with .cgi to be handled as a cgi script
#<Files *.cgi>
#      SetHandler cgi-script
#</Files>
# For FastCGI, comment the above line and uncomment the next 3 lines.
<Files *.cgi>
       SetHandler fastcgi-script
</Files>

You need to enable FastCGI in the domain Panel for the domain you are setting up.

This is safe.

# Set the default page to what ever is the default file.
# Use if you are using FastCGI and uncomment the next line
DirectoryIndex index.fcgi

FastCGI Errors

Most FastCGI errors can be tracked down in your site's error.log file (see logs/yourdomain.com/http/error.log). If you are having trouble making sense of the errors in the file, contact support and include the last few lines in your site's error.log file.

Logging In

You have two choices

1. Use the Log In Hack in the next section.
2. Use DB Authenticate in the Plugins section. Recommended: just follow the guide to install and configure

Log In Hack

Make sure you are in the directory of the public web site.

cd yourdomain.com

Copy the index file to admin for the log in hack

cp index.fcgi admin.fcgi

Go to your domain folder and create a .htaccess file:

nano .htaccess

In the editor add this text to the end and carefully change {USER}, {your.trac.environ}, and {path.to.trac} (where Trac is on your website; eg, if you have Trac available at http://example.com/trac, {path.to.trac} would be /trac):

# Authentication Hack
<Files "admin.fcgi">
      AuthType Basic
      AuthUserFile /home/{USER}/{your.trac.environ}/trac.htpasswd
      AuthName "Trac Sign In"
      require valid-user
</Files> 

# Make sure rewrites work
Options ExecCGI FollowSymLinks
 
# Make sure the Rewrite Module is installed
<IfModule mod_rewrite.c>
      RewriteEngine On
      RewriteRule ^index\.fcgi/login$ {path.to.trac}/admin.fcgi/login
      RewriteRule ^admin\.fcgi/logout$ {path.to.trac}/index.fcgi/logout
</IfModule>

Save and Close the file by pressing:

Ctrl+O
Ctrl+X

You will need to create the password file for the basic log in hack. Create the file in the location of the AuthUserFile in the .htaccess. You can change the AuthUserFile to the location of your password file.

Change to your Trac Environment

cd ~/{your.trac.environ}

Use htpasswd to create the password file (change tracAdminUserName to the username)

htpasswd -c trac.htpasswd tracAdminUserName

Afterwards it will prompt for a password which you type

New password: <type password>
Re-type new password: <type password again>
Adding password for user tracAdminUserName

If you want to create a new user, omit the -c parameter.

htpasswd trac.htpasswd NewUserName

And enter the password

New password: <type password>
Re-type new password: <type password again>
Adding password for user NewUserName

Add the Username in the password file to Trac. This will give the user full access to everything.

~/bin/trac-admin /home/{USER}/{your.trac.environ} permission add tracAdminUserName TRAC_ADMIN

There are more permissions you can assign to people, just read through trac-admin help permissions add and you'll see.

Pretty URLs

If you've followed the instructions here to install Trac using fcgi, and assuming that your Trac environment is /home/mysite/trac.mysite.com then your Trac URLs probably look something like http://trac.mysite.com/index.fcgi/wiki.

If you'd like to hide ugly the index.fcgi part of every Trac URL, try this hack:

Step 1: Hack the Trac base_url

Trac uses a variable called base_url to determine the root of the Trac URL for all links. When running Trac as cgi or fcgi, this is set to /index.fcgi internally. Currently (as of Trac 0.9.4, there is no graceful way to change this, but I found a easy way to hack it by editing the cgi_frontend.py script deep inside your python libraries:

 cd /home/{USER}/lib/python2.3/site-packages/trac/web

 # backup the original cgi_frontend.py in case you want to revert
 cp cgi_frontend.py cgi_frontend.py.orig

 # open cgi_frontend.py in your favorite editor
 nano cgi_frontend.py

On line 51, you'll see where self.cgi_location is set to self.__environ.get('SCRIPT_NAME'). We want to reassign self.cgi_location to the script's directory instead, and later use Apache mod_rewrite to make sure that index.fcgi is called behind the scenes. Edit line 51:

 # before:
          self.cgi_location = self.__environ.get('SCRIPT_NAME')

 # after:
          self.cgi_location = os.path.dirname(self.__environ.get('SCRIPT_NAME'))

Now, if you reload your Trac page and try to click on any internal link, the index.fcgi is left out of the URL. It won't work yet ... now to step 2

Step 2: RewriteRule

Go back to your Trac environment and edit your .htaccess file.

cd ~/trac.mysite.com
vim .htaccess

Make your .htaccess file look something like this. This assumes that you want the wiki page to show up as the default home page ... if you want it as something different, just change the DirectoryIndex line.

DirectoryIndex wiki

# Make sure rewrites work
Options ExecCGI FollowSymLinks

<IfModule mod_rewrite.c>
  RewriteEngine On
  RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-d
  RewriteCond %{DOCUMENT_ROOT}%{REQUEST_FILENAME} !-f
  RewriteCond $1 !^index.fcgi/(.*)
  # Keep the graphics and style sheet the way they are
  RewriteCond $1 !^(.*).css$
  RewriteCond $1 !^(.*).gif$
  RewriteCond $1 !^(.*).jpg$
  RewriteCond $1 !^(.*).png$
  RewriteRule ^(.*)$ index.fcgi/$1 [L]
</IfModule>

The RewriteCond and RewriteRule above maps every request by invisibly adding index.fcgi between the root and the URI. When you save and reload your Trac web page, you should see really nice looking URLs like http://trac.mysite.com/wiki/TracGuide.

Using Trac 0.9.6, with this method (a) I had to do a soft link "attachment" (singular) in the HTML directory to the directory "attachments" in the trac environment; (b) file names with spaces don't work [possibly unrelated], (c) only the first of several attachments shows up in the list. Anyone have more info or fixes for this? We have a dedicated server. Has anyone had success using ScriptAlias or ScriptAliasMatch? -Don sawtelle@stonecutter.com

If you have access to your httpd.conf file (which you don't on a Dreamhost shared server), then there is a more elegent way of doing this with ScriptAlias.

Troubleshooting DirectoryIndex

If the browser is not pointing to the file in the DirectoryIndex, then you can opt into using a normal index.php file with an internal redirect to the file you want. The host is configured to automatically go to any file named index.php, index.html, index.cgi, but not index.fcgi, which is why the DirectoryIndex is needed.

In case the DirectoryIndex is not working you might add an index.php files and change the DirectoryIndex:

nano .htaccess

And change the DirectoryIndex value (uncomment it if it's commented).

 DirectoryIndex index.php

Creating the index.php file

nano index.php

And write:

 <?php
   header('Location: index.fcgi'); //Or index.cgi, depending in which one you preffered
 ?>

Change the permissions on the .htaccess file

chmod 644 .htaccess

Plugins

Also, be sure and replace {USER}, with your shell username and {your.trac.environ} with your trac environment.

When installing plugins on a CGI or FastCGI environment, there may be a delay in the activation of the plugin. This will delay of fixing errors and when you're able to use the plugin. It Trac internal egg cache, but the plugins are activated and changed no later than 24 hours.

Ensure that the easy_install libraries are in your PYTHONPATH in the cgi/fcgi script, else links and eggs will not be activated.

Go to your Trac environment plugins folder.

cd ~/{your.trac.environ}/plugins

Recommended Plugins

• WebAdmin
• DB Authenticate

WebAdmin

WebAdmin is the Official web administration plugin for Trac. You can set it up globally or for each trac environment. This guide shows you how to set it up for each trac environment. You can find out how to do it globally by going to the Trac Plugin Guide, but it requires a little bit more work and you need to edit the

Find out which version to download, go the WebAdmin Plugin Page. These settings are for Trac 0.9.x and Python 2.3.

Download the plugin

wget http://projects.edgewall.com/trac/attachment/wiki/WebAdmin/TracWebAdmin-0.1.1dev_r2765-py2.3.egg.zip?format=raw

You have to remove the zip part and rename it so it isn't so big.

mv TracWebAdmin-0.1.1dev_r2765-py2.3.egg.zip TracWebAdmin.egg

At this point, if it is in your plugins folder then Trac should just pick it up and enable it. If not, then you need to edit your trac.ini file. It is recommended that you do this anyway, to minimize headache.

nano ~/{your.trac.environ}/conf/trac.ini

Scroll down to the bottom and add the components section if it doesn't exist already.

[components]
webadmin.* = enabled

DB Authenticate

Does not work with Account Manager Plugin. Recommended Plugin for form based log in.

Use if you want to have a form instead of using the Login hack. Further install instructions and howto at http://trac-hacks.org/wiki/DbAuthPlugin.

Checkout the plugin files

svn co http://trac-hacks.org/svn/dbauthplugin

Change directory to install

cd dbauthplugin/0.9/

Compile Egg

~/path/to/python setup.py bdist_egg

Move Egg to Plugin Folder

mv dist/TracDbAuth-0.1dev-py2.3.egg ~/{your.trac.environ}/plugins/TracDbAuth.egg

Change Directory to install folder

cd install

You need to build the tables for the Plugin to work.

~/path/to/sqlite user.db

After you type that the following lines will start with

sqlite>

Input the following after it.

Read the create-tables.sql

.read create-tables.sql

You need to populate the tables with insert statements. The author doesn't give any documentation, so just follow the directions. Change {username}, {password}, and {email} to the values you want.

INSERT INTO trac_users VALUES ('all', '{username}', '{password}', '{email}');

You will also need to add permissions for the user and use the same ones when you used the trac-admin. If you use a group then you need to make sure to use trac-admin to give the group permissions. If not then leave the group blank.

INSERT INTO trac_permissions VALUES ('all', '{username}', '{group}');

After you need to quit

.quit

Move the database to your trac environment

mv user.db ~/{your.trac.environ}/user.db

Remove the dbauth folder and type 'y' and enter if asked.

cd ../../../
rm -R dbauth

Edit the Trac Environment configuration file

nano ~/{your.trac.environ}/conf/trac.ini

Add the following at the bottom (From http://trac-hacks.org/wiki/DbAuthPlugin)

[components]
trac.web.auth.* = disabled
dbauth.* = enabled
trac.userdir.* = enabled  # only if you want to use this

[central]
database = /home/{your.shellusername}/{your.trac.environ}/user.db
envroot = /home/{your.shellusername}/

Account Manager

Does not work with DB Authenticate Plugin

The account manager allows Trac to manage the password file through the site. You still need to create the password file and add the first user.

Download the plugin

wget http://trac-hacks.org/download/accountmanagerplugin.zip

Unzip the File

unzip accountmanagerplugin.zip

Go to the Account Manager folder

cd accountmanagerplugin

Build the Plugin Egg

~/path/to/python setup.py bdist_egg

At this point there will be a lot of folders and files. You only need the egg.

cd dist

Move the Egg to the base plugin folder (Note, if you installed Python 2.4 then it will be py2.4 instead of py2.3)

mv TracAccountManager-0.1.2-py2.3.egg ~/{your.trac.environ}/plugins/TracAccountManager.egg

Remove the junk files

cd ../../
rm -R accountmanagerplugin
rm acountmanagerplugin.zip

You have to edit the configuration file.

nano ~/{your.trac.environ}/conf/trac.ini

Add the following to the end of the file and change the path of password_file to the path of the password file.

[account-manager]
password_format = htpasswd
password_file = /home/{USER}/{your.trac.environ}/trac.htpasswd

External Links

Natalian.org - Asked Dreamhost to install Debian Trac package.

Trac Project maintains the Trac Installation Guide. This may be useful for attempting to install the latest version of Trac and the associated tools.

Another how-to. My write up on installing Trac on my DreamHost account (2006-07-11)

Yet another how-to. A clear walk-through for installing Trac on a DreamHost account (2006-07-22)

Updated guide for 0.10.x. Natmaster's updated guide for new software versions. (2006-12-21)

Trac 0.10.x using MySQL. Modifications to Natmaster's guide for MySQL support, and a script to import your SQLite data into MySQL. (2007-01-11)

Working Trac Sites

[2] - Urduweb Software Projects

[3] - Firestorm Development Group International (DreamHost AMP Cluster)

Alternative Packages

Bugzilla - Is a far easier install and is wonderful for bug tracking.

www.mantisbt.org is a PHP bug tracker, so it will be the easiest to install.