From DreamHost

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..

Brain Dead Simple Installation

Ease of Install: One Click!

• Official DreamHost One-Click Installs, current version 0.11.4 (Uses FastCGI)

Create your SVN repository & Trac install together Already created Subversion Repo? Install Trac via One-Click Installs

Note: When you create a Trac install linked to a Subversion repository, it automatically sets up http authentication for the site based on the Subversion repository's htpasswd file and adds a default user anonymous with no password (to the Trac install only).

Troubleshoot Trac One-Click Install

Step by Step from the beginning (SVN+Trac)

The following method is the brain dead approach. It will install Trac and explains how to setup the accounts for Trac.

1. Create two empty domains (no files, no directories)
   1. Go to the webPanel -> Domains -> Manage Domains
      • svn.MySite.com this will be used for subversion
      • trac.MySite.com this will be used for trac
2. Wait until you get confirmation both sites are created
3. Go to the webpanel -> Goodies -> Subversion to create a new subversion project
   1. The SVN project should be installed svn.MySite.com/ProjectName
   2. Enable the checkbox "Add Trac Project Page"
   3. The Trac-software should be installed in to trac.MySite.com/ProjectName (sometimes it defaults to install it in svn.MySite.com/ProjectName so be careful)
   4. Check everything careful, double check the subdomains are set correct.
   5. Press "Create my new project repository now!"
4. Wait until you get three confirmations
   • 2 About SVN (first is about SVN is ready, but the website not, the second confirmation tells you the website is up)
   • 1 About Trac (this might take a while, but you should wait for it)
5. Go to the webpanel -> "Goodies" -> "Htaccess/WebDAV"
   1. Select trac.MySite.com/ProjectName
   2. Choose "Set Up a new Directory" (yes, this counter intuitive as the directory already exists but think "access" instead of "directory" and it should make sense)
   3. Fill in the directory name (which is ProjectName)
   4. Enable the checkbox in front of "Password-protect this dir?" (don't enable any other check boxes)
   5. Set the directory name and enter the usernames and passwords (I suggest you use the same values of when you setup SVN)
   6. Click "Configure This Directory"
6. Wait until you get confirmation
7. Go to trac.MySite.com/ProjectName and login. If everything went ok you should login.

You can repeat the above procedure (from point 3) with different project names and it should work.

Easier Installation

Ease of Install: Easy to Average

We have various scripts available to install Trac on Dreamhost (in order of creation, impartial)

• DreamTracInstall BSD License
• AutoTracOnDreamHost GPLv3 License
• dreamy-trac BSD License
• Creamy-Trac BSD License

Anyone of these scripts should be 100% easier to use than a manual install.

Please read TracInstall for more information about these scripts and what they have to offer.

Manual 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.4.4 or better
   • Some servers have Python 2.4.4 installed as python2.4 binary
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.

Permissions (Create Admins)

This is required whether you use DbAuth or the login hacks. For each user specify their access

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

You can also create groups, and assign permissions to groups

 trac-admin /home/{USER}/{your.trac.environ} permission add developers TICKET_CHGPROP
 trac-admin /home/{USER}/{your.trac.environ} permission add developers WIKI_MODIFY
 trac-admin /home/{USER}/{your.trac.environ} permission add developers WIKI_CREATE

ANd then add users to groups

 ~/bin/trac-admin /home/{USER}/{your.trac.environ} permission add john developers
 ~/bin/trac-admin /home/{USER}/{your.trac.environ} permission add mike developers

Of course once you create one admin you can do all this from the web interface.

Logging In

You have three choices

1. Use the Log In Hacks in the next section. (not recommended)
2. Use DB Authenticate in the Plugins section. Recommended: just follow the guide to install and configure
3. Use OpenID Plugin Best Option - works on Trac 0.11 See Plugins section for full install instructions.

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.

TO manage users with this Hack you have 2 options;

Use SVN Password File

Create your users through the DreamHost Panel and users can use the same credentials for svn and trac acess

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

Change Auth path to SNV password file

AuthUserFile /home/{USER}/svn/ProjectName.passwd

OR

Use New 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$
  RewriteCond $1 !^(.*).js$
  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

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

Troubleshooting database locked errors

With concurrent access to SQLite you may wish to build sqlite3 from source with the threadsafe option before installing trac.

Plugins

Using DreamHost's 'One-Click INstall'? Use openID plugin to avoid hassle of login hack and dbauth.

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

Installing with easy_install

To install a trac plugin from source, a typical usage is:

 easy_install --install-dir=$PYTHONPATH http://svn.source.of.plugin

AuthOpenID

The Concept / Goal

This plugin allows users to use OpenId to signin. This means you, or potential visitors/collaborators. You may still manage permissions on the back end.

Before you Start

These instructions are based on a one-click install on a DreamHost PS. Which means that python packages are the core,and not in a user's home - So you'll need a sudo shell account (see panel). If you are on a shared server you will need to specify the path to your own install of python, and do not need sudo access.

OpenID plugin Install

• open terminal
• browse to a location (i use a junk drawer type folder for things like this)

cd ~/install_files

• obtain the openid plugin (now moved to Bitbucket)

http://bitbucket.org/Dalius/authopenid-plugin/wiki/Home

• open plugin directory

cd authopenid-plugin

• install (PS Users)

sudo python setup.py install

• install (Shared Users)

python setup.py install

Element Tree

Element tree is a library used by python. If you notice an error in your logs like

ImportError: No ElementTree found. You may need to install one. Tried importing ['lxml.etree', 'xml.etree.cElementTree', 'xml.etree.ElementTree', 'cElementTree', 'elementtree.ElementTree'] 

than you need to install the library below.

• obtain ElementTree

wget http://effbot.org/media/downloads/elementtree-1.2.6-20050316.tar.gz

• open plugin directory

cd elementtree-1.2.6-20050316

• install (PS Users)

sudo python setup.py install

Final Configuration

Finally we enable the plugin through trac.ini

[components]
authopenid.* = enabled

We also need to eliminate the rewrite rules of the one-click install. Pretty URLs are useless if they break everything.

<Files *.cgi>
	SetHandler fastcgi-script
</Files>

DirectoryIndex index.fcgi

# Make sure rewrites work
Options ExecCGI FollowSymLinks

	RewriteEngine On

# fix missing logo issue
RewriteRule ^(index.fcgi/chrome/site/)(.*)$ ./chrome/site/$2

#force those visiting root to have index.fcgi in path (makes links work)
RewriteRule ^$ /<subdirectory_if_any>/index.fcgi/ [R]

Summing Up

Now anyone with an OpenID may sign into your site! You can use the backend to add your initial admin.

I highly recommend you create your own OpenID provider

Granting ADMIN permissions to a third party url may allow others to achieve admin rights

phpMyID is a great single user solution, and is as simple as uplaoding two files to your server. (DreamHost user's need to uncomment option one in the htaccess file, but thats all in the phpMyID README file)

You then set your url as the admin, since I setup phpMyID at the url http://openid.mydomain.com/, for me it might be

 trac-admin /path/to/trac/site permission add http://openid.mydomain.com/myid.config.php TRAC_ADMIN

SInce you'll be the only one who has the password for your installation this is a secure method.

Please add any errors you encounter to the discussion page!

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

Alternative Packages

• Redmine - Ruby on Rails issue tracker.
• Bugzilla - Perl-based, requires some module installations.
• www.mantisbt.org is a PHP bug tracker, so it will be the easiest to install.
• Flyspray is a PHP bug tracker. Handles multiple projects with separation and security. It works well in conjunction with DokuWiki for the Wiki capability.