trac-ticketlinks / wiki-default / TracInstall

= Trac Installation Guide =

The Trac web-based project management tool is implemented as a server
side cgi-program. Trac is written in the Python programming language
and uses SQLite as an embedded database. For HTML rendering, Trac uses the Clearsilver template system.

== Requirements ==

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

 * [ Python], version >= 2.1.
   * Please keep in mind, that for RPM-based systems you will also need python-devel and python-xml packages.
 * [ Subversion], version >= 0.37. (>=1.0.1 recommended)
 * [ Subversion Python bindings].
 * [ PySQLite], version >= 0.4.3 (>= 0.5 for better performance)
 * [ Clearsilver], version >= 0.9.3
 * A CGI-capable web server (we QA-test on [ Apache2] )

== Installing Trac ==
$ python ./ 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 [wiki:TracAdmin trac-admin] command-line tool, used to create and maintain project 
environments. Trac-admin is the ''command center'' of Trac.

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

For more information on installing Trac on specific platforms, see:

 * TracOnOsx
 * TracOnMandrakelinux
 * TracOnGentoo
 * TracOnFreeBsd
 * TracOnNetBsd
 * TracOnDebian
 * TracOnWindows
 * TracOnRedhat

=== Advanced Users ===
To install Trac in a different location, and other advanced installation options, run:
$ python ./ --help

== Creating a Project Environment ==

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

A new Trac environment is created with {{{trac-admin}}}:

$ trac-admin /path/to/projectenv initenv
'''Note:''' The web server user need write permission to the environment
directory and all the files inside.

[wiki:TracAdmin trac-admin] will ask you where your subversion repository is located and
where it can find the trac templates directory (the default value should be fine).

== Configuring Apache ==

Copy (or symlink) "{{{trac/cgi-bin/trac.cgi}}}" to 
you web servers {{{/cgi-bin/}}} directory. You can also configure apache
to use the "{{{trac/cgi-bin/}}}" directory directly if you like, it's a matter of taste.

Finally edit the apache config and add this config snippet, with filenams edited to match your installation:
Alias /trac/ "/usr/share/trac/htdocs/" #or where you installed the trac docs
#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

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

# 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

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

== Using Trac ==

You should now have a working Trac installation at:


There you should be able to browse your subversion repository, create tickets,
view the timeline etc. Keep in mind that anonymous users (not logged in)
can only access a restricted subset of all Trac features. 

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

For further user-documentation, see TracGuide.


See also:  TracGuide, TracPermissions, TracOnFreeBsd, TracOnNetBsd, TracOnOsx, TracOnMandrakelinux, TracOnDebian, TracOnGentoo