= 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:

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

== Installing Trac ==
{{{
$ 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 [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 ./setup.py --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
</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:''' 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:

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

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.

''Enjoy!''

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