Edgewall Software

Version 110 (modified by cshenton, 19 years ago) ( diff )

—

This page documents the 1.4 (latest stable) release. Documentation for other releases can be found here.

Trac Installation Guide

Table of Contents

The Trac WEB-based project management tool is implemented as a CGI- or standalone program. Trac is written in the ​Python programming language and uses the ​SQLite embedded database for persistent storage. For HTML rendering, Trac uses the ​Clearsilver template system.

Note: These are generic instructions for installing and setting up Trac and its requirements. You should first look at TracInstallPlatforms for instructions and downloads specific to the system where you are installing Trac.

Requirements

To install Trac, the following software packages must be installed:

  • ​Python, version ≥ 2.1 (≥2.3 recommended).
    • Python 2.1 support is going to be dropped for the next (0.9) release of Trac. Minimum required version for trunk is thus Python 2.2.0 (see #1311 and ​this mail).
    • Please keep in mind, that for RPM-based systems you will also need python-devel and python-xml packages.
    • Make sure you get the version of Python for which there are Subversion bindings, as of writing is 2.3. Don't install Python 2.4 just to realize the Python 2.3 Subversion bindings don't work with it, like what happened to me.
  • ​Subversion, version ≥ 1.0. (≥ 1.1 recommended)
  • ​Subversion Python bindings. Trac uses the ​SWIG bindings included in the Subversion distribution, not the ​PySVN package! Also note that the Subversion bindings have problems with versions of SWIG ≥ 1.3.22, so using 1.3.21 is strongly recommended at this point.
  • ​SQLite, version 2.8.x or 3.0.x
  • ​PySQLite, version 1.0.x (for SQLite 2.8.x), version 1.1.x (for SQLite 3.0.x) (I had to use pysqlite-1.1.6 which installed as …/site-packages/sqlite; pysqlite-2.0.3 installed as pysqlite2 so imports failed and symlinking it to "sqlite" caused error identified by #1589)
  • ​Clearsilver, version ≥ 0.9.3
  • Note: On debian you will need to install python-dev to get the distutils.core package.

Optional Packages

Installing Trac

Like most Python programs, install the Trac python modules by running the following command at the top of the source directory: 

$ python ./setup.py install

This will byte-compile the python source code and install it in the site-packages directory of your python installation. The directories cgi-bin, templates, htdocs and wiki-default are all copied to $prefix/share/trac/ .

The script will also install the trac-admin command-line tool, used to create and maintain project environments.

The trac-admin program is the control center for Trac.

Note: you'll need root permissions or equivalent for this step.

For more information on installing Trac on specific platforms, see the ​TracInstallPlatforms page (on the main project web site).

Advanced Users

To install Trac in a custom location, and view other advanced install options, run: 

$ python ./setup.py --help

Specifically, you might be interested in 

$ python ./setup.py install --prefix=/path/you/want

Creating a Project Environment

TracEnvironment is the backend storage format where Trac stores information like wiki pages, tickets, reports, settings, etc. An environment consist of a directory containing an SQLite database, human-readable configuration file, log-files and attachments.

A new Trac environment is created using trac-admin, like: 

$ trac-admin /path/to/projectenv initenv

trac-admin will ask you where your subversion repository is located and where it can find the trac templates directory (the default value should work for a typical install).

Note: The web server user will require file system write permission to the environment directory and all the files inside. Remember to set the appropriate permissions.

The same applies for the subversion repository files (unless using the ​FSFS Subversion backend, something we highly recommend).

Configuring Apache

Make "trac/cgi-bin/trac.cgi" accessible to your web server at /cgi-bin/, either by copying/symlinking or use the "trac/cgi-bin/" directory directly.

Note: If you are symlinking "trac/cgi-bin/trac.cgi" make sure you have the FollowSymLinks option set for CGI directory in the apache config.

Edit the apache config and add this snippet, filenames edited to match your installation: 

Alias /trac/ /usr/share/trac/htdocs/
#or where you installed the trac htdocs
#You have to allow people to read the files in htdocs
<Directory "/usr/share/trac/htdocs">
 Options Indexes MultiViews
 AllowOverride None
 Order allow,deny
 Allow from all
</Directory>


# Trac need to know where the database is located
<Location "/cgi-bin/trac.cgi">
 SetEnv TRAC_ENV "/path/to/projectenv"
</Location>

# You need this to allow users to authenticate
# trac.htpasswd can be created with 
# cmd 'htpasswd -c trac.htpasswd' (UNIX)
# do 'man htpasswd' to see all the options
<Location "/cgi-bin/trac.cgi/login">
 AuthType Basic
 AuthName "trac"
 AuthUserFile /somewhere/trac.htpasswd
 Require valid-user
</Location>

Note: You can also use Trac via mod_python. Read TracModPython for more information.

Note: If Apache complains about the SetEnv line make sure you have the LoadModule for mod_env uncommented (Apache 1.3).

Note: When creating a new environment, trac-admin will print a config snippet customized for your project.

Note: If you are using ​Apache suEXEC feature see ​ApacheSuexec (on the project web site).

Using Trac

Congratulations''' You should now have a running Trac installation at:

http://<yourhostname>/cgi-bin/trac.cgi

You should be able to browse your subversion repository, create tickets, view the timeline and use all the features of Trac.

Keep in mind that anonymous users (not logged in) can only access a restricted subset of all Trac features by default.

Note: If you don't want long, and relatively ugly, URLs, you can prettify them by changing your Apache config. See TracPrettyUrls.

Please continue to TracPermissions to learn how to grant additional privileges to authenticated users.

For user documentation, see TracGuide.

Enjoy''

​The Trac Team

See also: TracGuide, TracUpgrade, TracPermissions, TracInstallPlatforms, TracModPython

Note: See TracWiki for help on using the wiki.