Source

trac-ticketlinks / INSTALL

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.2.
   + 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.4 recommended)
 * Subversion Python bindings.
 * PySQLite, version >= 0.5 (1.1.6 recommended)
 * Clearsilver, version >= 0.9.3 (0.9.14 recommended)
 * A CGI-capable web server (we QA-test on Apache2)

Note that trac can also use run in standalone mode (see README.tracd)


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 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.

Advanced Users
--------------
To install Trac in a different location, and 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. 

 * NOTE: The windows installer also includes the Clearsilver DLL, so you do
   *NOT* have to install it manually when using the installer.

After running the installer, configuration and installation is the same as
for other platforms.

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.

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 filenames
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!

/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/>
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.