Trac Installation Guide
=======================
Trac is a lightweight project management tool that is implemented as a
web-based application. Trac is written in the Python programming language and
can use SQLite or PostgreSQL as  database. For HTML rendering, Trac uses the
Clearsilver templating system.


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

 * Python, version >= 2.3.
   + Please keep in mind, that for RPM-based systems you will also need
   python-devel and python-xml packages.
 * Subversion, version >= 1.0. (>= 1.1.x recommended)
 * Subversion SWIG Python bindings (not PySVN).
 * PySQLite, version >= 0.5 (1.1.6 recommended)
 * Clearsilver, version >= 0.9.3 (0.9.14 recommended)
 * A web server capable of executing CGI/FastCGI scripts, or Apache HTTPD with
   mod_python. (Trac also comes with a standalone server, but its use is not
   recommended for use in a production environment.)


Installing Trac
---------------
The command:

  $ python ./setup.py install

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. Trac-admin is the command center of Trac.

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

To install Trac in a different location, or use other advanced installation
options, run:

  $ python ./setup.py --help


Installing Trac on Windows
--------------------------
If you downloaded the Trac installer (the .exe file), installing is simply a
matter of running the installer.  After running the installer, configuration
and installation is the same as for other platforms.


Creating a Project Environment
------------------------------
A Trac environment is the backend storage format where Trac stores information
like wiki pages, tickets, reports, settings, etc. A Trac environment consists
of the environment configuration file (trac.ini), custom templates, log files,
and more.

A new Trac environment is created with trac-admin:

  $ trac-admin /path/to/projectenv initenv

Note: The user account under which the web server is run needs write permission
to the environment directory and all the files inside.

trac-admin will prompt you for the name of the project, where your subversion
repository is located, what database you want to use, etc.


Running the Standalone Server
-----------------------------
After having created a Trac environment, you can easily try the web interface
by running the standalone server tracd:

  $ tracd --port 8000 /path/to/projectenv

Then, fire up a browser and visit http://localhost:8000/. You should get a
simple listing of all environments that tracd knows about. Follow the link
to the environment you just created, and you should see Trac in action.


Running Trac on a Web Server
----------------------------
Trac provides three options for connecting to a "real" web server: CGI, FastCGI
and mod_python. For decent performance, it is recommended that you use either
FastCGI or mod_python.

Please refer to the TracInstall page for details on these setups. You can find
it either in the wiki of the Trac project you just created, or on the main Trac
site.


Using Trac
----------
Once you have your Trac site up and running, you should be able to browse your
subversion repository, create tickets, view the timeline, etc.

Keep in mind that anonymous (not logged in) users can by default access most
but not all of the features. You will need to configure authentication and
grant additional permissions to authenticated users to see the full set of
features.

For further documentation, see the TracGuide wiki page.

Enjoy!

/The Trac Team

Please also consider joining the mailing list at
<http://lists.edgewall.com/mailman/listinfo/trac/>.


Visit the Trac open source project at <http://trac.edgewall.com/>