= Trac Installation Guide =
[[TracGuideToc]]

The Trac web-based project management tool is implemented as a CGI- or standalone program. Trac is written in the [http://www.python.org/ Python] programming language
and uses the [http://www.sqlite.org/ SQLite] embedded database for persistant storage. For HTML rendering, Trac uses the [http://www.clearsilver.net/ Clearsilver] template system.


== Requirements ==

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

 * [http://www.python.org/ Python], version >= 2.1 (>=2.3 recommended).
   * 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 >= 1.0. (>=1.1 recommended)
 * [http://svnbook.red-bean.com/svnbook-1.1/ch08s02.html#svn-ch-8-sect-2.3 Subversion Python bindings] (Caveat: Trac uses the [http://www.swig.org/ SWIG] bindings included in the Subversion distribution,  '''not''' the  [http://pysvn.tigris.org/ PySVN] package!)
 * [http://www.sqlite.org/ SQLite], version 2.8.x or 3.0.x
 * [http://pysqlite.sf.net/ PySQLite], version >= 0.5 but < 1.1.0 (for SQLite 2.8.x), version >= 1.1.1 (for SQLite 3.0.x) 
 * [http://clearsilver.net/ Clearsilver], version >= 0.9.3
 * [http://docutils.sourceforge.net/ docutils], version >= 0.3.3 (??)
 * A CGI-capable web server (tested on [http://httpd.apache.org/ Apache] )

=== Optional Packages ===

 * [http://www.modpython.org/ mod_python] (see TracModPython)

== 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 [wiki:TracAdmin trac-admin] command-line tool, used to create and maintain [wiki:TracEnvironment project environments]. 

The [wiki:TracAdmin 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 [http://projects.edgewall.com/trac/wiki/TracInstallPlatforms 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
}}}

== 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 [wiki:TracAdmin trac-admin], like:

{{{
$ trac-admin /path/to/projectenv initenv
}}}

[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 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 [http://svn.collab.net/repos/svn/trunk/notes/fsfs 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.

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:''' If Apache complains about the Set''''''Env line make sure you have the Load''''''Module 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 [http://httpd.apache.org/docs/suexec.html Apache suEXEC] feature see [http://projects.edgewall.com/trac/wiki/ApacheSuexec 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 [http://projects.edgewall.com/trac/wiki/TracPrettyUrls TracPrettyUrls] (on the project website).

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

For user documentation, see TracGuide.

''Enjoy!''

[http://projects.edgewall.com/trac/wiki/TracTeam The Trac Team]

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